Introduction

What is Screena ?

Screena is a REST API that provides endpoints to match and resolve multicultural name datasets. Our technology leverages multi-cultural attributes and culture-specific algorithms as well as artificial intelligence proprietary techniques.

This documentation is organized by solution and method.

Each solution includes an overview, as well as a description of configurable options and a list of supported methods. The panel on the right includes code samples in a variety of programming languages. You can select your preferred language with the tabs at the top of the panel.

How Screena works

The task of precisely matching names has always been a tremendous challenge because until now there was simply no universal way of solving all potential pitfalls. Misspellings, acronyms, spelling differences, missing or out-of-order components, and so on make it a tough problem to solve ! While applying one technique to address a specific pain point, you might well create another … and fall into a dilemma situation.

This is where Screena kicks in: we provide software and tools to help you make every name-match accurate and insightful. No need for you to hire cohorts of data scientists and software engineers to solve this issue. We provide what you need to address your rapidly evolving business objectives without having to care about name-matching difficult challenges.

Screena consists of three solutions, each having a specific focus: reducing drastically false positives when matching names and entities, reducing false negatives in an unprecedented way, and managing searches and matches with large datasets without facing speed or performance constraints.

Just pick the solution you need !

Coders First

Even though we are obsessed with the quality of the content delivered to Screena’s users, and primarily coders (we are coders too and we know what a terrible experience a poor product doc can be), we also know that nobody and nothing is perfect in this world.

Having said that, we would love to get your feedback if you find anything good or bad while reading our docs. All contributions that can help us provide the best possible content are always appreciated. Nothing is as delightful as a happy coder !

API Information

Versions

API version 1 is now deprecated: Screena server component supports only API version 2 and all calls are assumed to be version 2.

Current version is 2.1.17.

The API documentation was last updated on December 18th, 2023.

Service Status

Visit Screena Status Page to check the API service status across all supported regions and stay informed during downtime.

Release Notes

Check Screena Help Center for all Release Notes.

Endpoints

This chapter lists all of the Endpoints exposed in the Screena API.

Matching Endpoints

Solution	Verb	Path	Description
Screena One	`POST`	`rest/v2/name-match`	Matching Full Names Matching Parsed Names
Screena Plus	`POST`	`rest/v2/entity-match`	Matching Individuals Matching Organizations Matching Vessels Matching MRTD Matching Narratives
Screena Firm	`POST`	`rest/v2/dataset-search` `rest/v2/dataset-search-engine` `rest/v2/dataset-search-engine-ongoing`	Searching Datasets Integrating Watchlist Screening Integrating Watchlist Screening (Periodic Screening)
Screena Firm	`POST`	`rest/v2/dataset-search-engine-export` `rest/v2/dataset-search-engine-export-pdf`	Exporting Search Reports (CSV) Exporting Search Reports (PDF)
Screena Firm	`POST`	`rest/v2/dataset-match`	Matching Datasets

Datasets Endpoints

Solution	Verb	Path	Description
Screena Firm	`POST`	`rest/v2/datasets/edit`	Creating Datasets (In)activating Datasets
Screena Firm	`GET`	`rest/v2/datasets`	Listing Datasets
Screena Firm	`DELETE`	`rest/v2/datasets/delete/{label}`	Deleting Datasets
Screena Firm	`POST`	`rest/v2/datasets/post-records`	Posting Records
Screena Firm	`POST`	`rest/v2/datasets/bulk-import`	Dataset Bulk Importing
Screena Firm	`POST`	`rest/v2/datasets/edit-records`	(In)activating Records
Screena Firm	`POST`	`rest/v2/datasets/browse-records`	Browsing Records
Screena Firm	`DELETE`	`rest/v2/datasets/delete/{label}/record/{dataID}`	Deleting Records

Tasks Management Endpoints

Solution	Verb	Path	Description
Screena Firm	`GET`	`rest/v2/tasks/{taskID}`	Getting a Task’s Status
Screena Firm	`GET`	`rest/v2/dataset-match/{taskID}` `rest/v2/dataset-match/positives/{taskID}` `rest/v2/dataset-match/negatives/{taskID}`	Getting Match Results

Libraries Endpoints

Solution	Verb	Path	Description
Screena Firm	`POST`	`rest/v2/libraries/populate`	Populating Prefixes Library Populating Suffixes Library Populating Stopwords Library Populating Synonyms Library Populating Locations Library
Screena Firm	`POST`	`rest/v2/libraries/bulk-import`	Library Bulk Importing
Screena Firm	`GET`	`rest/v2/libraries/{library}`	Browsing Libraries

Toolbox Endpoints

Solution	Verb	Path	Description
Screena Firm	`GET`	`rest/v2/datasets/keywords/{label}`	Retrieving Keywords

Format

The Screena API uses JSON encoded as UTF-8.

The body of POST requests must be either a JSON object or a JSON array (depending on the particular endpoint) with Content-Type: application/json; charset=UTF-8.

The body of responses is always a JSON object, always provided with Content-Type: application/json; charset=UTF-8.

Authentication

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/name-match"

To use the Screena API you must have an API key.

The API key is a unique identifier that is used to authenticate requests associated with your project for usage and billing purposes.

Since the API key itself is an identity by which to identify the application or the user, it is unique, random and non-guessable.

Before you can start using the Screena API, you must sign up and create a billing account. Include your API key in all API requests to the server via a HTTP header: "X-Screena-API-Key: your_api_key"

The Screena API POST methods accept the use of a JSON header envelope containing a requestID.

To avoid confusion, it should be noted that the header envelope only applies to POST methods. For example, no requestID is used in GET methods.

Request Attributes

Request

{
    "requestHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc27"
    }
}

Attribute	Description	Required
`requestID` String	Unique identifier of the request.	No

How it works — By default, the Screena application generates a unique identifier for every incoming HTTPS request that it receives.

This unique identifier is then passed to your application as an HTTPS header called requestID.

Alternately, for a tighter integration, you can specify your own requestID when making a request:

The requestID value must be between 20 and 200 characters.
Invalid requestID will generate an error message.
Your application code can then read this requestID and log it or use it for other purposes.
requestID having the same value as previously sent to the API will generate an error message.

For batch-based requests, please check here.

Response Attributes

Response

Parameters for responses are provided into responseHeader.

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc27-1588831643171",
        "responded": "2020-05-07T06:07:23.171Z"
    }
}

Attribute	Description
`requestID` String	Unique identifier of the related request.
`responded` String	Date/Time at which the response was sent. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.

Screena One

Matching Full Names

This POST method allows to send one to many match queries using full names in a single API call. The method matches all combinatorially possible combinations of the names in sourceData with the names in targetData.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/name-match"

Request: The following example is the most basic request you can post to the API. In this case the entitytype is not provided and the threshold is set at its default value, which is to say 60%.

Endpoint: POST rest/v2/name-match

{
    "queries": [{
        "sourceData": [{
            "names": [{
                "fullName": "Mr. Johnathan Smith"
            }]
        }],
        "targetData": [{
            "names": [{
                "fullName": "John Smith"
            }]
        }]
    }]
}

Attribute	Description	Required
`sourceData` Array of Data Objects	Set of source data to run the match query from.	Yes
`dataID` String	Unique identifier of the data record.	No
`entityType` String	Type of Named-Entities that has to be matched. Refer to Named-Entities Objects for more info.	No
`names` Array of Name Objects	Name data to match in any and all scripts. At least one name attribute must be provided.	Yes
`fullName` String	Full Name to match.	Yes
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those of `sourceData`.	Yes
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "GEN2054093905-1620367528448",
        "responded": "2021-05-07T06:05:28.448Z"
    },
    "results": [{
        "matchType": "st_match",
        "score": 0.80,
        "sourceData": [{
            "entityType": "unknown",
            "names": [{
                "fullName": "Mr. Johnathan Smith",
                "normalized": "johnathan smith"
            }],
            "cultureCodes": [
                "en"
            ]
        }],
        "targetData": [{
            "entityType": "unknown",
            "names": [{
                "fullName": "John Smith",
                "normalized": "john smith"
            }],
            "cultureCodes": [
                "cy",
                "en",
                "ga",
                "no",
                "sv"
            ]
        }]
    }]
}

Returns an array of match results.

Attribute	Description
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. Scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`sourceData` Array of Data Objects	Set of source data returned in the match result.
`dataID` String	Unique identifier of the data record as it was posted to the API.
`entityType` String	Type of Named-Entities used for the match. This field is always returned, even if it was not provided in the match query (i.e.: unknown). Refer to Named-Entities Objects for more info.
`names` Array of Name Objects	Name data used for the match.
`fullName` String	Full Name as it was posted to the API.
`normalized` String	Normalized value that was used for the match. Refer to Normalization for more info.
`cultureCodes` Array of Strings	Code(s) of the culture(s) associated with the name, as detected by Screena. Refer to Name Cultures for more info.
`targetData` Array of Data Objects	Set of target data returned in the match result. The child attributes of `targetData` are the same as those of `sourceData`.

How it works — Screena does NOT work at all like a standard matching engine which solely compares phonetic similarities or measures the distance between 2 strings. Screena does much more than that: it emulates human analysis.

Standard scores (st_match) are returned by the application when 2 strings are so obviously similar that consequently AI is not required.
AI-based scores (i.e. ai_accept or ai_reject) are returned by the application for non-obvious matching cases. AI is used to determine the probability that 2 strings are the same, and thus solves many problems associated to similarity measures.

In the provided example, the similarity between "Mr. Jonathan Smith" and "John Smith" is only 53% with the Levenshtein algorithm ! With Screena the score is 80%. This is closer to the reality, as we experience it as human beings, when interacting with names.

To learn more, please see Name-matching Algorithms.

Matching Parsed Names

This POST method allows to send one to many match queries using parsed names in a single API call. Parsed names attributes provide more granularity and increases the overall quality of the results.

The method matches all combinatorially possible combinations of the names in sourceData with the names in targetData.

Request Attributes

Endpoint: POST rest/v2/name-match

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/name-match"

Request: Such request is particularly useful when a targetdata record (typically from a watchlist) is provided with names’ alternative spellings, original scripts or variations. Similarly, when the source data contains alternative spellings, original scripts or variations, the API can be provided with multiple values. The below example uses all the standard attributes for better results as well as dataID, which makes possible to address Records uniquely, so that they can be accessed and interacted within a third-party application. Also, in this example the threshold is set to 90%.

{
    "requestHeader": {
        "requestID": "555-415-1337-00ub0oNGTSWTBKOLGLNR"
    },
    "queries": [{
        "sourceData": [{
            "dataID": "1",
            "entityType": "individual",
            "names": [{
                "givenName": "Abdul Latif",
                "surname": "MANSUR"
            }]
        }],
        "targetData": [{
            "dataID": "38403",
            "entityType": "individual",
            "names": [{
                    "fullName": "ABDUL ABDUL LATIF MANSUR"
                },
                {
                    "fullName": "Abdul Latif Mansoor"
                },
                {
                    "fullName": "MANSUR ABDUL LATIF"
                }
            ]
        }],
        "threshold": 0.90
    }]
}

Attribute	Description	Required
`sourceData` Array of Data Objects	Set of source data to run the match query from.	Yes
`dataID` String	Unique identifier of the data record.	No
`entityType` String	Type of Named-Entities that has to be matched. Refer to Named-Entities Objects for more info.	No
`names` Array of Name Objects	Name data to match. At least one name attribute must be provided.	Yes
`givenName` String	Given Name to match.	No
`surname` String	Surname to match.	No
`fatherName` String	Father Name to match.	No
`motherName` String	Mother Name to match.	No
`fullName` String	Full Name to match.	No
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those of `sourceData`	Yes
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No

Watch out — Do not use fullName with any other name attributes in the same block such as:

surname
givenName
fatherName
motherName

Only surname, givenName, fatherName, motherName can be used in the same block.

So, either you provide full names or parsed names in the same block but not both together.

Otherwise, Screena will generate an error message.

Also, the response will always provide normalized as a full name even when the request provided parsed names!

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "555-415-1337-00ub0oNGTSWTBKOLGLNR",
        "responded": "2021-05-07T06:13:09.635Z"
    },
    "results": [{
            "matchType": "st_match",
            "score": 0.98,
            "sourceData": [{
                "dataID": "1",
                "entityType": "individual",
                "names": [{
                    "surname": "MANSUR",
                    "givenName": "Abdul Latif",
                    "normalized": "abdul latif mansur"
                }],
                "cultureCodes": [
                    "ar"
                ]
            }],
            "targetData": [{
                "dataID": "38403",
                "entityType": "individual",
                "names": [{
                    "fullName": "ABDUL ABDUL LATIF MANSUR",
                    "normalized": "abdul abdul latif mansur"
                }],
                "cultureCodes": [
                    "ar"
                ]
            }]
        },
        {
            "matchType": "st_match",
            "score": 0.98,
            "sourceData": [{
                "dataID": "1",
                "entityType": "individual",
                "names": [{
                    "surname": "MANSUR",
                    "givenName": "Abdul Latif",
                    "normalized": "abdul latif mansur"
                }],
                "cultureCodes": [
                    "ar"
                ]
            }],
            "targetData": [{
                "dataID": "38403",
                "entityType": "individual",
                "names": [{
                    "fullName": "Abdul Latif Mansoor",
                    "normalized": "abdul latif mansour"
                }],
                "cultureCodes": [
                    "ar"
                ]
            }]
        },
        {
            "matchType": "st_match",
            "score": 0.98,
            "sourceData": [{
                "dataID": "1",
                "entityType": "individual",
                "names": [{
                    "surname": "MANSUR",
                    "givenName": "Abdul Latif",
                    "normalized": "abdul latif mansur"
                }],
                "cultureCodes": [
                    "ar"
                ]
            }],
            "targetData": [{
                "dataID": "38403",
                "entityType": "individual",
                "names": [{
                    "fullName": "MANSUR ABDUL LATIF",
                    "normalized": "mansur abdul latif"
                }],
                "cultureCodes": [
                    "ar"
                ]
            }]
        }
    ]
}

Returns an array of match results.

Attribute	Description
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. Scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`sourceData` Array of Data Objects	Set of source data returned in the match result.
`dataID` String	Unique identifier of the data record as it was posted to the API.
`entityType` String	Type of Named-Entities used for the match. This field is always returned, even if it was not provided in the match query (i.e.: unknown). Refer to Named-Entities Objects
`names` Array of Name Objects	Name data used for the match.
`givenName` String	Given Name as it was posted to the API.
`surname` String	Surname as it was posted to the API.
`fatherName` String	Father Name as it was posted to the API.
`motherName` String	Mother Name as it was posted to the API.
`fullName` String	Full Name as it was posted to the API.
`normalized` String	Normalized value that was used for the match. Refer to Normalization for more info.
`cultureCodes` Array of Strings	Code(s) of the culture(s) associated with the name, as detected by Screena. Refer to Name Cultures for more info.
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those of `sourceData`

Remember — Screena allows you to post several queries in a single request:

Multiple queries shall be sent using the regular POST method to the relevant endpoint.
The method and URL do not change.
The request and response attributes used in multiple queries are identical to the above-described formats.
Individual response arrays included in the response JSON might appear in a different order than in the request JSON.

Screena Plus

Matching Individuals

This POST method allows to send one to many match queries using individuals' attributes in a single API call. It uses similarities of the individual names but also other key attributes such as date of birth, country of birth, address, and nationality, which uniquely identify an individual. Results are based on any combination of available attributes provided through the API.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/entity-match"

Request (Individual)

Endpoint: POST rest/v2/entity-match

{
    "requestHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc33"
    },
    "queries": [{
        "sourceData": [{
            "dataID": "174",
            "entityType": "individual",
            "names": [{
                "givenName": "maria",
                "surname": "callas"
            }, {
                "fullName": "Anna Maria Sophia Cecilia Kaloyeropoulou"
            }],
            "sex": "F",
            "nationalities": [{
                "country": "US"
            }, {
                "country": "GR"
            }],
            "datesOfBirth": [{
                "date": "1923-12-02"
            }],
            "placesOfBirth": [{
                "city": "New-York",
                "country": "US"
            }],
            "addresses": [{
                "street": "36 avenue Georges Mandel",
                "city": "Paris",
                "country": "FR"
            }]
        }],
        "targetData": [{
            "dataID": "455",
            "entityType": "individual",
            "names": [{
                "fullName": "Μαρία Κάλλας"
            }, {
                "fullName": "Sophia Cecilia Kalos"
            }],
            "nationalities": [{
                "country": "GR"
            }],
            "datesOfBirth": [{
                "date": "1922/1925"
            }, {
                "date": "1928"
            }],
            "addresses": [{
                "city": "Athens",
                "country": "GR"
            }, {
                "city": "Paris",
                "country": "FR"
            }]
        }],
        "threshold": 0.90,
        "entityTypeAlgo": {
            "type": "exact_match",
            "nullMatch": true
        },
        "sexAlgo": {
            "type": "exact_match",
            "nullMatch": true
        },
        "nationalityAlgo": {
            "type": "same_country",
            "nullMatch": true
        },
        "dateOfBirthAlgo": {
            "type": "same_year",
            "nullMatch": true
        },
        "placeOfBirthAlgo": {
            "type": "same_country",
            "nullMatch": true
        },
        "addressAlgo": {
            "type": "same_country",
            "nullMatch": true
        }
    }]
}

Attribute	Description	Required
`sourceData` Array of Data Objects	Set of source data to run the match query from.	Yes
`dataID` String	Unique Identifier of the data record.	No
`entityType` String	Type of Named-Entities that has to be matched: shall be an individual. Refer to Named-Entities Objects for more info.	Yes individual
`names` Array of Name Objects	Name data to match in any and all scripts. At least one name attribute must be provided.	Yes
`givenName` String	Given Name to match.	No
`surname` String	Surname to match.	No
`fatherName` String	Father Name to match.	No
`motherName` String	Mother Name to match.	No
`fullName` String	Full Name to match.	No
`sex` String	Sex for an individual. Refer to Sexes and Genders for more info.	No
`nationalities` Array of Location Objects	Nationality for an individual, can be many. See child attributes for Countries.	No
`categories` Array of Category Objects	Class or division of individuals regarded as having particular shared characteristics, can be many.	No
`datesOfBirth` Array of Date Objects	Date of birth for an individual, can be many. Refer to Dates for more info.	No
`placesOfBirth` Array of Location Objects	Place of birth for an individual, can be many. See child attributes for Places.	No
`addresses` Array of Location Objects	Address for an individual, can be many. See child attributes for Addresses.	No
`identityDocuments` Array of Identity Document Objects	Identity Document for an individual, can be many. See child attributes for Identity Documents.	No
`digitalCurrencies`(New) Array of Digital Currency Objects	Digital Currency related data, can be many. See child attributes for Digital Currencies.	No
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those of `sourceData`.	Yes
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No
`entityTypeAlgo` Algorithm Object	Type of algorithms to match straightforward values. Refer to Binary-Matching Algorithms for more info.	No
`sexAlgo` Algorithm Object	Type of algorithms to match straightforward values. Refer to Binary-Matching Algorithms for more info.	No
`nationalityAlgo` Algorithm Object	The type of algorithms used for matching countries. Refer to Country-Matching Algorithms for more info.	No
`dateOfBirthAlgo` Algorithm Object	The type of algorithms used for matching dates. Refer to Date-Matching Algorithms for more info.	No
`placeOfBirthAlgo` Algorithm Object	The type of algorithms used for matching countries. Refer to Country-Matching Algorithms for more info.	No
`addressAlgo` Algorithm Object	The type of algorithms used for matching countries. Refer to Country-Matching Algorithms for more info.	No
`identityDocumentAlgo`(New) Algorithm Object	The type of algorithms used for matching identity document numbers. Refer to Identifier-Matching Algorithms for more info.	No
`digitalCurrencyAlgo` Algorithm Object	The type of algorithms used for matching digital currency identifiers. Refer to Identifier-Matching Algorithms for more info.	No
`categoryAlgo`(New) Algorithm Object	The type of algorithms used for matching categories associated with data records. Refer to Binary-Matching Algorithms for more info.	No
`keywordAlgo`(New) Algorithm Object	The type of algorithms used for matching keywords associated with data records. Refer to Binary-Matching Algorithms for more info.	No

Remember — Don't be surprised that placesOfBirth or datesOfBirth are multiple. No one doubts that human beings can only be born in one place on the same date ! However, in some Datasets when data about some persons are uncertain or messy such illogical situations occur frequently.

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc33",
        "responded": "2022-07-15T08:32:05.061Z"
    },
    "results": [{
            "matchType": "st_match",
            "score": 0.94,
            "sourceData": [{
                "dataID": "174",
                "entityType": "individual",
                "names": [{
                    "surname": "callas",
                    "givenName": "maria",
                    "normalized": "maria callas"
                }],
                "sex": "F",
                "cultureCodes": [
                    "bg",
                    "ca",
                    "co",
                    "da",
                    "de",
                    "el",
                    "en",
                    "es",
                    "eu",
                    "fi",
                    "fy",
                    "gl",
                    "hu",
                    "is",
                    "it",
                    "nl",
                    "no",
                    "oc",
                    "pl",
                    "pt",
                    "ro",
                    "ru",
                    "sc",
                    "sk",
                    "sv",
                    "uk"
                ],
                "nationalities": [{
                    "country": "GR",
                    "normalized": "GR"
                }],
                "datesOfBirth": [{
                    "date": "1923-12-02",
                    "normalized": "1923"
                }],
                "addresses": [{
                    "street": "36 avenue Georges Mandel",
                    "city": "Paris",
                    "country": "FR",
                    "normalized": "FR"
                }],
                "placesOfBirth": [{
                    "city": "New-York",
                    "country": "US"
                }]
            }],
            "targetData": [{
                "dataID": "455",
                "entityType": "individual",
                "names": [{
                    "fullName": "Μαρία Κάλλας",
                    "normalized": "maria kallas"
                }],
                "sex": "u",
                "cultureCodes": [
                    "XX"
                ],
                "nationalities": [{
                    "country": "GR",
                    "normalized": "GR"
                }],
                "datesOfBirth": [{
                    "date": "1922/1925",
                    "normalized": "1922/1925"
                }],
                "addresses": [{
                    "city": "Paris",
                    "country": "FR",
                    "normalized": "FR"
                }],
                "placesOfBirth": [{
                    "country": "XX"
                }]
            }]
        },
        {
            "matchType": "ai_reject",
            "score": 0.30,
            "unmatched": [
                "names"
            ],
            "sourceData": [{
                "dataID": "174",
                "entityType": "individual",
                "names": [{
                    "surname": "callas",
                    "givenName": "maria",
                    "normalized": "maria callas"
                }],
                "sex": "F",
                "cultureCodes": [
                    "bg",
                    "ca",
                    "co",
                    "da",
                    "de",
                    "el",
                    "en",
                    "es",
                    "eu",
                    "fi",
                    "fy",
                    "gl",
                    "hu",
                    "is",
                    "it",
                    "nl",
                    "no",
                    "oc",
                    "pl",
                    "pt",
                    "ro",
                    "ru",
                    "sc",
                    "sk",
                    "sv",
                    "uk"
                ],
                "nationalities": [{
                    "country": "GR",
                    "normalized": "GR"
                }],
                "datesOfBirth": [{
                    "date": "1923-12-02",
                    "normalized": "1923"
                }],
                "addresses": [{
                    "street": "36 avenue Georges Mandel",
                    "city": "Paris",
                    "country": "FR",
                    "normalized": "FR"
                }],
                "placesOfBirth": [{
                    "city": "New-York",
                    "country": "US"
                }]
            }],
            "targetData": [{
                "dataID": "455",
                "entityType": "individual",
                "names": [{
                    "fullName": "Sophia Cecilia Kalos",
                    "normalized": "sophia cecilia kalos"
                }],
                "sex": "u",
                "cultureCodes": [
                    "de",
                    "en"
                ],
                "nationalities": [{
                    "country": "GR",
                    "normalized": "GR"
                }],
                "datesOfBirth": [{
                    "date": "1922/1925",
                    "normalized": "1922/1925"
                }],
                "addresses": [{
                    "city": "Paris",
                    "country": "FR",
                    "normalized": "FR"
                }],
                "placesOfBirth": [{
                    "country": "XX"
                }]
            }]
        },
        {
            "matchType": "ai_reject",
            "score": 0.60,
            "unmatched": [
                "names"
            ],
            "sourceData": [{
                "dataID": "174",
                "entityType": "individual",
                "names": [{
                    "fullName": "Anna Maria Sophia Cecilia Kaloyeropoulou",
                    "normalized": "anna maria sophia cecilia kaloyeropoulou"
                }],
                "sex": "F",
                "cultureCodes": [
                    "bg",
                    "ca",
                    "co",
                    "da",
                    "de",
                    "el",
                    "en",
                    "es",
                    "eu",
                    "fi",
                    "fy",
                    "gl",
                    "hu",
                    "is",
                    "it",
                    "nl",
                    "no",
                    "oc",
                    "pl",
                    "pt",
                    "ro",
                    "ru",
                    "sc",
                    "sk",
                    "sv",
                    "uk"
                ],
                "nationalities": [{
                    "country": "GR",
                    "normalized": "GR"
                }],
                "datesOfBirth": [{
                    "date": "1923-12-02",
                    "normalized": "1923"
                }],
                "addresses": [{
                    "street": "36 avenue Georges Mandel",
                    "city": "Paris",
                    "country": "FR",
                    "normalized": "FR"
                }],
                "placesOfBirth": [{
                    "city": "New-York",
                    "country": "US"
                }]
            }],
            "targetData": [{
                "dataID": "455",
                "entityType": "individual",
                "names": [{
                    "fullName": "Sophia Cecilia Kalos",
                    "normalized": "sophia cecilia kalos"
                }],
                "sex": "u",
                "cultureCodes": [
                    "de",
                    "en"
                ],
                "nationalities": [{
                    "country": "GR",
                    "normalized": "GR"
                }],
                "datesOfBirth": [{
                    "date": "1922/1925",
                    "normalized": "1922/1925"
                }],
                "addresses": [{
                    "city": "Paris",
                    "country": "FR",
                    "normalized": "FR"
                }],
                "placesOfBirth": [{
                    "country": "XX"
                }]
            }]
        },
        {
            "matchType": "no_match",
            "unmatched": [
                "names"
            ],
            "sourceData": [{
                "dataID": "174",
                "entityType": "individual",
                "names": [{
                    "fullName": "Anna Maria Sophia Cecilia Kaloyeropoulou",
                    "normalized": "anna maria sophia cecilia kaloyeropoulou"
                }],
                "sex": "F",
                "cultureCodes": [
                    "bg",
                    "ca",
                    "co",
                    "da",
                    "de",
                    "el",
                    "en",
                    "es",
                    "eu",
                    "fi",
                    "fy",
                    "gl",
                    "hu",
                    "is",
                    "it",
                    "nl",
                    "no",
                    "oc",
                    "pl",
                    "pt",
                    "ro",
                    "ru",
                    "sc",
                    "sk",
                    "sv",
                    "uk"
                ],
                "nationalities": [{
                    "country": "GR",
                    "normalized": "GR"
                }],
                "datesOfBirth": [{
                    "date": "1923-12-02",
                    "normalized": "1923"
                }],
                "addresses": [{
                    "street": "36 avenue Georges Mandel",
                    "city": "Paris",
                    "country": "FR",
                    "normalized": "FR"
                }],
                "placesOfBirth": [{
                    "city": "New-York",
                    "country": "US"
                }]
            }],
            "targetData": [{
                "dataID": "455",
                "entityType": "individual",
                "names": [{
                    "fullName": "Μαρία Κάλλας",
                    "normalized": "maria kallas"
                }],
                "sex": "u",
                "cultureCodes": [
                    "XX"
                ],
                "nationalities": [{
                    "country": "GR",
                    "normalized": "GR"
                }],
                "datesOfBirth": [{
                    "date": "1922/1925",
                    "normalized": "1922/1925"
                }],
                "addresses": [{
                    "city": "Paris",
                    "country": "FR",
                    "normalized": "FR"
                }],
                "placesOfBirth": [{
                    "country": "XX"
                }]
            }]
        }
    ]
}

Returns an array of match results.

Attribute	Description
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. AI scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`unmatched` Array of Strings	Provide the unmatched attributes when the `matchType` is "no_match" or "ai_reject", as detected by Screena.
`sourceData` Array of Data Objects	Set of source data returned in the match result.
`dataID`	Unique identifier of the data record as it was posted to the API.
`entityType` String	Type of Named-Entities used for the match. This field is always returned, even if it was not provided in the match query (i.e.: unknown). Refer to Named-Entities Objects for more info.
`names` Array of Name Objects	Name data used for the match.
`givenName` String	Given Name as it was posted to the API.
`surname` String	Surname as it was posted to the API.
`fatherName` String	Father Name as it was posted to the API.
`motherName` String	Mother Name as it was posted to the API.
`fullName` String	Full Name as it was posted to the API.
`normalized` String	Normalized value that was used for the match. Refer to Normalization for more info.
`cultureCodes` Array of Strings	Code(s) of the culture(s) associated with the name, as detected by Screena. Refer to Name Cultures for more info.
`sex` String	Sex for an individual, only returned if filtered by an algorithm. Refer to Sexes and Genders for more info.
`nationalities` Array of Location Objects	Nationality for an individual, only returned if filtered by an algorithm. See child attributes for Countries.
`datesOfBirth` Array of Date Objects	Date of birth for an individual, only returned if filtered by an algorithm. Refer to Dates for more info.
`placesOfBirth` Array of Location Objects	Place of birth for an individual, only returned if filtered by an algorithm. See child attributes for Places.
`addresses` Array of Location Objects	Address for an individual, only returned if filtered by an algorithm. See child attributes for Addresses.
`digitalCurrencies`(New) Array of Digital Currency Objects	Digital Currency related data, only returned if filtered by an algorithm. See child attributes for Digital Currencies.
`targetData` Array of Data Objects	Set of target data returned in the match result. The child attributes of `targetData` are the same as those of `sourceData`.

Matching Organizations

This POST method allows to send one to many match queries using organizations' attributes in a single API call. It uses similarities of the organization names but also other key attributes such as registry date, place of registry, and address which uniquely identify an organization. Results are based on any combination of available attributes provided through the API.

Request Attributes

Endpoint: POST rest/v2/entity-match

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/entity-match"

Request (Organization)

{
    "requestHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc34"
    },
    "queries": [{
        "sourceData": [{
            "dataID": "2890",
            "entityType": "organization",
            "names": [{
                "fullName": "Rosoboronexport"
            }],
            "datesOfRegistry": [{
                "date": "2000-11-04"
            }],
            "placesOfRegistry": [{
                "country": "RU"
            }],
            "addresses": [{
                "street": "24 Usacheva ul.",
                "city": "Moscow"
            }]
        }],
        "targetData": [{
            "dataID": "3015",
            "entityType": "organization",
            "names": [{
                "fullName": "Rosoboronexport (ROE)"
            }, {
                "fullName": "Рособоронэкспорт"
            }]
        }],
        "threshold": 0.65
    }]
}

Attribute	Description	Required
`sourceData` Array of Data Objects	Set of source data to run the match query from.	Yes
`dataID` String	Unique Identifier of the data record.	No
`entityType` String	Type of Named-Entities that has to be matched: shall be an organization. Refer to Named-Entities Objects for more info.	Yes organization
`names` Array of Name Objects	Name data to match in any and all scripts. At least one name attribute must be provided.	Yes
`fullName` String	Full Name to match.	Yes
`bic`(New) String	Business Identifier Code (BIC) data to match (8-11 characters).	No
`lei`(New) String	Legal Entity Identifier (LEI) data to match (20 characters).	No
`datesOfRegistry` Array of Date Objects	Date of registration for an organization, can be many. Refer to Dates for more info.	No
`placesOfRegistry` Array of Location Objects	Place of registration for an organization, can be many. See child attributes for Places.	No
`addresses` Array of Location Objects	Address for an organization, can be many. See child attributes for Addresses.	No
`identityDocuments` Array of Identity Document Objects	Identity Document for an organization, can be many. See child attributes for Identity Documents.	No
`categories` Array of Category Objects	class or division of organizations regarded as having particular shared characteristics, can be many.	No
`digitalCurrencies`(New) Array of Digital Currency Objects	Digital Currency related data, can be many. See child attributes for Digital Currencies.	No
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those of `sourceData`.	Yes
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No
`entityTypeAlgo` Algorithm Object	Type of algorithms to match straightforward values. Refer to Binary-Matching Algorithms for more info.	No
`dateOfRegistryAlgo` Algorithm Object	The type of algorithms used for matching dates. Refer to Date-Matching Algorithms.	No
`placeOfRegistryAlgo` Algorithm Object	The type of algorithms used for matching countries. Refer to Country-Matching Algorithms for more info.	No
`identityDocumentAlgo`(New) Algorithm Object	The type of algorithms used for matching identity document numbers. Refer to Identifier-Matching Algorithms for more info.	No
`addressAlgo` Algorithm Object	The type of algorithms used for matching countries. Refer to Country-Matching Algorithms for more info.	No
`bicAlgo`(New) Algorithm Object	Type of algorithms to match straightforward values. Refer to Identifier-Matching Algorithms for more info.	No
`leiAlgo`(New) Algorithm Object	Type of algorithms to match straightforward values. Refer to Identifier-Matching Algorithms for more info.	No
`digitalCurrencyAlgo`(New) Algorithm Object	The type of algorithms used for matching Digital Currency Identifiers. Refer to Identifier-Matching Algorithms for more info.	No
`categoryAlgo`(New) Algorithm Object	The type of algorithms used for matching categories associated with data records. Refer to Binary-Matching Algorithms for more info.	No
`keywordAlgo`(New) Algorithm Object	The type of algorithms used for matching keywords associated with data records. Refer to Binary-Matching Algorithms for more info.	No

Watch out — The next version of our software will support multiple values for all data fields, including placesOfRegistry, placesOfIssue, datesOfRegistry, datesOfIssue, and datesOfExpiry. However, it is important to note that this version does not yet support arrays that can store multiple values for these fields. Currently, the software can only store a single value for each of these fields in the format of placeOfRegistry, placeOfIssue, dateOfRegistry, dateOfIssue, and dateOfExpiry.

If you require the ability to store multiple values for these fields, we recommend that you wait for the upcoming version 3.0, which will include this feature. We apologize for any inconvenience this may cause and appreciate your patience as we work to improve our software and add more features.

Request (BIC entity-attribute)

{
    "queries": [{
        "sourceData": [{
            "bic": "AFAB AFKA"
        }],
        "targetData": [{
            "bic": "AFABAFKA"
        }],
        "bicAlgo": {
            "type": "exact_match",
            "nullMatch": true
        }
    }]
}

Remember — About Matching BIC and LEI codes as well as Digital Currency Identifiers.

The international standard ISO 9362 specifies the elements and the structure of a universal identification code, the Business Identifier Code (BIC), which is used by financial and non-financial institutions, for which such an international identifier is required in order to facilitate automated processing of information.

The Legal Entity Identifier (LEI) alpha-numeric code based on the ISO 17442 standard developed by the International Organization for Standardization (ISO) connects to key reference information that enables clear and unique identification of legal entities participating in financial transactions.

A digital currency address is an alphanumeric identifier that represents a potential destination for a digital currency transfer. A digital currency address is uniquely associated with a digital currency wallet.

In the context of Financial Crime Compliance, each incoming and outgoing transactions must be screened for a potential match with sanctions lists, including BIC and LEI codes as well as digital currency identifiers.

Screena allows fields to be matched with varying degrees of specificity including the use of BIC and LEI codes as well as digital currency identifiers that substitute or complement name information. For commodity purposes, BIC and LEI codes as well as digital currency identifiers can be either considered as an attribute of an organization or as a standalone entity-attribute.

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc34",
        "responded": "2021-05-05T10:08:01.722Z"
    },
    "results": [{
            "matchType": "st_match",
            "score": 0.93,
            "sourceData": [{
                "dataID": "2890",
                "entityType": "organization",
                "names": [{
                    "fullName": "Rosoboronexport",
                    "normalized": "rosoboronexport"
                }]
            }],
            "targetData": [{
                "dataID": "3015",
                "entityType": "organization",
                "names": [{
                    "fullName": "Rosoboronexport (ROE)",
                    "normalized": "rosoboronexport roe"
                }]
            }]
        },
        {
            "matchType": "st_match",
            "score": 0.94,
            "sourceData": [{
                "dataID": "2890",
                "entityType": "organization",
                "names": [{
                    "fullName": "Rosoboronexport",
                    "normalized": "rosoboronexport"
                }]
            }],
            "targetData": [{
                "dataID": "3015",
                "entityType": "organization",
                "names": [{
                    "fullName": "Рособоронэкспорт",
                    "normalized": "rosoboroneksport"
                }]
            }]
        }
    ]
}

Returns an array of match results.

Attribute	Description
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. AI scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`unmatched` Array of Strings	Provide the unmatched attributes when the `matchType` is "no_match" or "ai_reject", as detected by Screena.
`sourceData` Array of Data Objects	Set of source data returned in the match result.
`dataID` String	Unique Identifier of the data record.
`entityType` String	Type of Named-Entities used for the match. This field is always returned, even if it was not provided in the match query (i.e.: unknown). Refer to Named-Entities Objects.
`names` Array of Name Objects	Name data used for the match.
`bic`(New) String	BIC data used for the match, only returned if filtered by an algorithm.
`lei`(New) String	LEI data used for the match, only returned if filtered by an algorithm.
`fullName` String	Full Name as it was posted to the API.
`normalized` String	Normalized value that was used for the match. Refer to Normalization for more info.
`datesOfRegistry` Array of Date Objects	This is the date of registration for a organization, only returned if filtered by an algorithm. See child attributes for Dates.
`placesOfRegistry` Array of Location Objects	This is the place of registration for an organization, only returned if filtered by an algorithm. See child attributes for Places.
`addresses` Array of Location Objects	Address for an organization, only returned if filtered by an algorithm. See child attributes for Addresses.
`digitalCurrencies`(New) Array of Digital Currency Objects	Digital Currency related data, only returned if filtered by an algorithm. See child attributes for Digital Currencies.
`targetData` Array of Data Objects	Set of target data returned in the match result. The child attributes of `targetData` are the same as those of `sourceData`.

Matching Vessels

This POST method allows to send one to many match queries using vessels' attributes in a single API call. It uses similarities of the vessel names but also other key attributes such as build date, place of build, and flag, which uniquely identify an vessel. Results are based on any combination of available attributes provided through the API.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/entity-match"

Endpoint: POST rest/v2/entity-match

Request (Vessel)

{
    "requestHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc34"
    },
    "queries": [{
        "sourceData": [{
            "dataID": "23659",
            "entityType": "vessel",
            "names": [{
                "fullName": "Maersk Mc-Kinney Moller"
            }],
            "flags": [{
                "country": "DK"
            }],
            "datesOfBuild": [{
                "date": "2013"
            }]
        }],
        "targetData": [{
            "dataID": "3015",
            "entityType": "vessel",
            "names": [{
                "fullName": "MAERSKMCKINNEYMOLLER"
            }]
        }],
        "threshold": 0.65
    }]
}

Attribute	Description	Required
`sourceData` Array of Data Objects	Set of source data to run the match query from.	Yes
`dataID` String	Unique Identifier of the data record.	No
`entityType` String	Type of Named-Entities that has to be matched: shall be a vessel. Refer to Named-Entities Objects for more info.	Yes organization
`names` Array of Name Objects	Name data to match in any and all scripts. At least one name attribute must be provided.	Yes
`fullName` String	Full Name to match.	Yes
`flags` Array of Location Objects	Flags of vessel, can be many. See child attributes for Countries.	No
`datesOfBuild` Array of Date Objects	Date at which the vessel was completed, can be many. See child attributes for Dates.	No
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those of `sourceData`.	Yes
`identityDocuments` Array of Identity Document Objects	Identity Document for an organization, can be many. See child attributes for Identity Documents.	No
`categories` Array of Category Objects	class or division of vessels regarded as having particular shared characteristics, can be many.	No
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No
`entityTypeAlgo` Algorithm Object	Type of algorithms to match straightforward values. Refer to Binary-Matching Algorithms for more info.	No
`flagAlgo` Algorithm Object	The type of algorithms used for matching countries. Refer to Country-Matching Algorithms.	No
`dateOfBuildAlgo` Algorithm Object	The type of algorithms used for matching dates. Refer to Date-Matching Algorithms.	No
`identityDocumentAlgo`(New) Algorithm Object	The type of algorithms used for matching identity document numbers. Refer to Identifier-Matching Algorithms for more info.	No
`categoryAlgo`(New) Algorithm Object	The type of algorithms used for matching categories associated with data records. Refer to Binary-Matching Algorithms for more info.	No
`keywordAlgo`(New) Algorithm Object	The type of algorithms used for matching keywords associated with data records. Refer to Binary-Matching Algorithms for more info.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc34",
        "responded": "2020-05-27T17:20:58.820Z"
    },
    "results": [{
        "matchType": "st_match",
        "score": 0.98,
        "sourceData": [{
            "dataID": "23659",
            "entityType": "vessel",
            "names": [{
                "fullName": "Maersk Mc-Kinney Moller",
                "normalized": "maersk mc kinney moller"
            }]
        }],
        "targetData": [{
            "dataID": "3015",
            "entityType": "vessel",
            "names": [{
                "fullName": "MAERSKMCKINNEYMOLLER",
                "normalized": "maerskmckinneymoller"
            }]
        }]
    }]
}

Returns an array of match results.

Attribute	Description
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. AI scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`unmatched` Array of Strings	Provide the unmatched attributes when the `matchType` is "no_match" or "ai_reject", as detected by Screena.
`sourceData` Array of Data Objects	Set of source data returned in the match result.
`dataID` String	Unique Identifier of the data record.
`entityType` String	Type of Named-Entities used for the match. This field is always returned, even if it was not provided in the match query (i.e.: unknown). Refer to Named-Entities Objects.
`names` Array of Name Objects	Name data used for the match.
`fullName` String	Full Name as it was posted to the API.
`normalized` String	Normalized value that was used for the match. Refer to Normalization for more info.
`flags` Array of Location Objects	Flags of vessel, only returned if filtered by an algorithm. See child attributes for Countries.
`datesOfBuild` Array of Date Objects	Date at which the vessel was completed, only returned if filtered by an algorithm. See child attributes for Dates.
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those of `sourceData`.

Matching MRTD

Machine-Readable Travel Documents (MRTD) are standardized by the ICAO Document 9303 (endorsed by the International Organization for Standardization and the International Electrotechnical Commission as ISO/IEC 7501-1) and have a special machine-readable zone (MRZ), which is usually at the bottom of the identity page at the beginning of a passport. ICAO Document 9303 describes 4 document types using an MRZ of which we support two (MRTD Type 1 and Type 3):

The MRZ of a Type 1 travel document spans 3 lines, and each line is 30 characters long. Usually passport booklets are issued in "Type 3" format. Identity cards and passport cards typically use the "Type 1" format.
The MRZ of a Type 3 travel document spans 2 lines, and each line is 44 characters long. The following information must be provided in the zone: name, passport number, nationality, date of birth, sex, and passport expiration date. There is room for optional, often country-dependent, supplementary information. Usually passport booklets are issued in "Type 3" format.

Screena can directly parse the information found on MRTDs.

So instead of manually entering information from individuals and sending the value of each field, the MRZ can be read by an optical character recognition device and sent to Screena's API. This enables faster processing, and greater accuracy than manually read passports, as well as faster data entry, and better data matching against immigration databases and watchlists.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/entity-match"

Request (Individual)

Endpoint: POST rest/v2/entity-match

{
    "requestHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc33"
    },
    "queries": [{
        "sourceData": [{
            "dataID": "174",
            "mrz": [{
                "line1": "P<USAKALOYEROPOULOU<<ANNA<MARIA<SOPHIA<CECI<",
                "line2": "7070146083USA2312020F2305075<<<<<<<<<<<<<<<8"
            }]
        }],
        "targetData": [{
            "dataID": "455",
            "entityType": "individual",
            "names": [{
                "fullName": "Μαρία Κάλλας"
            }, {
                "fullName": "Sophia Cecilia Kalos"
            }],
            "nationalities": [{
                "country": "GR"
            }],
            "datesOfBirth": [{
                "date": "1922/1925"
            }, {
                "date": "1928"
            }],
            "addresses": [{
                "city": "Athens",
                "country": "GR"
            }, {
                "city": "Paris",
                "country": "FR"
            }]
        }],
        "threshold": 0.80,
        "entityTypeAlgo": {
            "type": "exact_match",
            "nullMatch": true
        },
        "sexAlgo": {
            "type": "exact_match",
            "nullMatch": true
        },
        "nationalityAlgo": {
            "type": "same_country",
            "nullMatch": true
        },
        "dateOfBirthAlgo": {
            "type": "same_year",
            "nullMatch": true
        },
        "placeOfBirthAlgo": {
            "type": "same_country",
            "nullMatch": true
        },
        "addressAlgo": {
            "type": "same_country",
            "nullMatch": true
        }
    }]
}

Attribute	Description	Required
`mrz` Array of MRZ Objects	MRZ data to match. At least two lines must be provided.	No
`line1` String	MRZ first line for either MRTD Type 1 (30 characters) or MRTD Type 3 (44 characters).	Yes
`line2` String	MRZ second line for either MRTD Type 1 (30 characters) or MRTD Type 3 (44 characters).	Yes
`line3` String	MRZ third line for MRTD Type 1 (30 characters) only. Do not provide for Type 3 MRTD.	No

Remember — You can use mrz in both sourceData and targetData.

The functioning is exactly similar than for matching individuals, which is to say:

It is possible to match information captured from a MRZ against any and all individuals or another MRZ.
The information coming from the MRZs is automatically typed as being those from an individual (i.e. entityType is set to "individual").

Response Attributes

Response attributes are similar than those provided when matching individuals.

Matching Narratives

In the field of Financial Crime Compliance, Narratives are used in different contexts:

they are used in STR (Suspicious Transaction Reports) to narrate the events leading to a suspicion of money laundering activities, including other information which might be of importance to the FIU (Financial Investigation Unit).
they are widely used in payment messages to provide a narrative description in addition to structured information, which will allow the recipient of the message to obtain a sufficient level of information that cannot be reflected in structured data alone (e.g., remittance information, instruction for next agent, instruction for creditor's agent, regulatory reporting, etc).
they are used in watchlists to provide a narrative description in addition to structured information about an entity, which provides detailed information about the person sanctioned or prosecuted by the police.

Screena proposes an end-to-end solution to minimize the human labeling effort for entity matching on unstructured data sets, and particularly in Narratives. We use several text analytics techniques that clearly outperform comparable entity matching approaches on an unstructured real world data set.

Remember — Keep in mind the following when using narrative.

narrative can only be used in sourceData. In future versions, it will be possible to use narrative in targetData as well.
narrative cannot be used in conjunction with other attributes, it must always be sent alone, independent of other data. Typically, when screening SWIFT messages, narrative and structured information shall be sent with two different requests.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/entity-match"

Request

Endpoint: POST rest/v2/entity-match

{
    "requestHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc34"
    },
    "queries": [{
        "sourceData": [{
            "dataID": "2890",
            "narrative": "bashar al assad is nearly on every sanction list and is obviously not one of our clients"

        }],
        "targetData": [{
            "dataID": "3015",
            "entityType": "individual",
            "names": [{
                "fullName": "bashar al assad "
            }]
        }],
        "threshold": 0.65
    }]
}

Attribute	Description	Required
`sourceData` Array of Data Objects	Set of source data to run the match query from.	Yes
`dataID` String	Unique Identifier of the data record.	No
`narrative` String	Narrative to match: unstructured data of up to 5000 characters.	No
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those that you can find in `sourceData` of Individuals, Organizations, and Vessels.	Yes
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No

Response Attributes

Response attributes are similar than those provided when matching organizations or unknown entities.

Response: The JSON response presented as an example is limited for simplification reasons. All the non-matching elements returned in the response are not displayed in the example.

{
    "matchType": "st_match",
    "score": 1.00,
    "sourceData": [{
        "dataID": "2890",
        "entityType": "unknown",
        "names": [{
            "fullName": "bashar al assad",
            "normalized": "bashar al assad"
        }],
        "cultureCodes": [
            "ar"
        ],
        "narrative": "bashar al assad is nearly on every sanction list and is obviously not one of our clients"
    }],
    "targetData": [{
        "dataID": "3015",
        "entityType": "individual",
        "names": [{
            "fullName": "bashar al assad ",
            "normalized": "bashar al assad"
        }],
        "cultureCodes": [
            "ar"
        ]
    }]
}

Attribute	Description
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. AI scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`unmatched` Array of Strings	Provide the unmatched attributes when the `matchType` is "no_match" or "ai_reject", as detected by Screena.
`sourceData` Array of Data Objects	Set of source data returned in the match result.
`dataID` String	Unique Identifier of the data record.
`narrative` String	Narrative used for the match: unstructured data of up to 5000 characters.
`entityType` String	Type of Named-Entities used for the match. This field is always returned, even if it was not provided in the match query (i.e.: unknown). Refer to Named-Entities Objects.
`names` Array of Name Objects	Name data used for the match.
`fullName` String	Full Name as it was posted to the API.
`targetData` Array of Data Objects	Set of target data to run the match query against. The child attributes of `targetData` are the same as those of `sourceData`.
`cultureCodes` Array of Strings	Code(s) of the culture(s) associated with the name, as detected by Screena. Refer to Name Cultures for more info.

Screena Firm

Screena Firm is a full-featured, comprehensive solution, which can be used to match and search internal and external (including open-source and proprietary) data.

Asynchronous Tasks — Screena Firm can involve large amount of data.

Consequently, some crucial Screena Firm methods require asynchronous (batch-based) processes. It means that when you use such methods, typically Bulk Importing and Matching Datasets, Screena Firm adds a new task into a background process. It is this task and not the method that performs the desired action. When the background process has many pending tasks, any new added task has to wait its turn.

For every asynchronous request a taskID is generated:

You can use this taskID to manage dependencies when a particular task has to complete before proceeding with a new request.
You can also use taskID to check where a large matching query stands before retrieving its results.

On the other hand, Screena Firm also provides synchronous (one-at-a-time) processes like Searching Datasets and also Posting Records for smaller Datasets.

Last but not least, Screena Firm can also work with stream-processing software such as RabbitMQ, Kafka, and ActiveMQ technologies for integration patterns based on events and asynchronous messaging, thus ensuring maximum scalability and resiliency.

Our experts are available to answer your technical questions about Screena Firm and help you find the solution you need. Drop us an email: experts@screena.ai

Getting a Task’s Status

Due to the volumes at stake, it may be necessary that while waiting for a process to complete you need to be informed about its status.

At any time, you can use the below GET method to determine where this task stands.

Request Attributes

curl -s -X GET \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   "https://screena.ai/rest/v2/tasks/9340a7d73ef9499f1adff6e76b01e39d"

Endpoint: GET rest/v2/tasks/{taskID}

The query string is sent in the URL of the GET request. You need to pass the relevant label into the query string too.

Response Attributes

Response

{
    "taskID": "9340a7d73ef9499f1adff6e76b01e39d",
    "type": "matching",
    "dataset": "COMPANY 1",
    "started": "2020-04-17T14:30:15.321+01:00",
    "ended": "2020-04-17T14:33:20.321+01:00",
    "status": "in progress",
    "totalCount": "1000",
    "duration": "PT3M5S"
}

Attribute	Description
`taskID` String	Unique identifier of the asynchronous task.
`started` String	Date/Time when the task was started. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`ended` String	Date/Time when the task was ended. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`type` String	Type of task, can be "matching", "importing", or "indexing".
`status` String	Status of the task, can be "in progress", "completed", or "failed".
`totalCount` String	Total number of Records that need to be processed.
`dataset` String	When a "matching" task is ongoing, identifies the source Dataset. When an "importing" or "indexing" task is ongoing, identifies the Dataset under processing.
`duration` String	Effective task duration since it was started. Provided in ISO 8601 format: P[n]Y[n]M[n]DT[n]H[n]M[n]S.

Creating Datasets

Before you start doing anything with Screena Firm, you need to create Datasets. This POST method allows to you to send a request to the API to do so.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/edit"

Request: Create a Dataset

Endpoint: POST rest/v2/datasets/edit

{
    "datasets": [{
        "label": "COMPANY 1",
        "category": "CUSTOMER DATA"
    }]
}

Attribute	Description	Required
`label` String	Unique Name of the Dataset that shall exist in the Screena Firm repository.	Yes
`category` String	Category is used for organizing the Datasets into groups that can be categorized in some way similar to each other. It can be a watchlist, a grey list, a customer list, etc.	No
`active` Boolean	If `active` is true, the dataset and all the Records contained inside are active and can be searched and matched upon. If `active` is false, the dataset and all the Records contained inside can't be matched or searched. If `active` is not provided, Screena will set the parameter at true.	No

Response Attributes

Response: Successful creation of the Dataset

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true
}

Returns a confirmation message that the Dataset(s) was/were successfully created.

Attribute	Description
`success` Boolean	If `success` is true, the Dataset is successfully created. Otherwise an error is returned.

Watch out — If you send a duplicate label, Screena will return an error.

It is important to keep in mind that Screena manages unicity of Datasets through their label.

(In)activating Datasets

You can inactivate and reactivate but never rename Datasets.

You simply have to set the active attribute to either false or true based on your needs.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/edit"

Endpoint: POST rest/v2/datasets/edit

Request: Inactivate a Dataset

{
    "datasets": [{
        "label": "COMPANY 1",
        "active": false
    }]
}

Attribute	Description	Required
`label` String	Unique Name of the Dataset that shall exist in the Screena Firm repository.	Yes
`active` Boolean	If `active` is true, the dataset and all the Records contained inside are active and can be searched and matched upon. If `active` is false, the dataset and all the Records contained inside can't be matched or searched. If `active` is not provided, Screena will set the parameter at true.	No

Response Attributes

Response: Successful inactivation of the Dataset

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true
}

Returns a confirmation message that the Dataset was successfully inactivated or reactivated.

Attribute	Description
`success` Boolean	If `success` is true, the Dataset is successfully inactivated or reactivated. Otherwise an error is returned.

Watch out — If you inactivate a Dataset all the Records included into this Dataset will be inactivated too. It effectively means that their attribute active will be set to false.

Listing Datasets

This GET method allows to retrieve and list all Datasets created into the Screena Firm repository.

Request Attributes

curl -s -X GET \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   "https://screena.ai/rest/v2/datasets"

Endpoint: GET rest/v2/datasets

The query string is sent in the URL of the GET request.

Response Attributes

Response

{
    "responseHeader": {
        "responded": "2020-07-17T15:30:15.321+01:00"
    },
    "datasets": [{
            "label": "COMPANY 1",
            "active": true,
            "category": "CUSTOMER DATA",
            "created": "2021-09-13T10:18:23.709",
            "totalCount": "2000"
        },
        {
            "label": "COMPANY 2",
            "active": true,
            "category": "CUSTOMER DATA",
            "created": "2021-09-13T10:18:23.709",
            "totalCount": "251230"
        },
        {
            "label": "WATCHLIST 1",
            "active": true,
            "category": "PROPRIETARY",
            "created": "2021-09-13T10:18:23.709",
            "totalCount": "8997"
        },
        {
            "label": "UN",
            "active": true,
            "category": "SANCTION",
            "created": "2021-09-13T10:18:23.709",
            "totalCount": "934",
            "dateOfPublication": "2023-04-27T19:08:39.145",
            "dateOfUpload": "2023-05-05T02:45:36.66"
        }
    ]
}

Attribute	Description
`label` String	Name of the Dataset, which shall be unique.
`created` String	Creation Date/Time of the Dataset. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`active` Boolean	If `active` is true, the dataset and all the Records contained inside are active and can be searched and matched upon. If `active` is false, the dataset and all the Records contained inside can't be matched or searched.
`totalCount` Integer	Count of the total number of Records with which the Dataset is currently populated.
`category` String	Category is used for organizing the Datasets into groups that can be categorized in some way similar to each other.
`dateOfPublication` String	Latest official Publication Date/Time by the owner of the source. Only returned for the Datasets included in our official set of supported Watchlists. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`dateOfUpload` String	Latest Upload Date/Time into the Screena Firm repository. Only returned for the Datasets included in our official set of supported Watchlists. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.

Deleting Datasets

This DELETE method allows to delete Datasets into the Screena Firm Repository. Contrary to an inactivation, this method ensures hard deletion.

Request Attributes

curl -s -X DELETE \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   "https://screena.ai/rest/v2/datasets/delete/COMPANY&nbsp;2"

Endpoint: DELETE rest/v2/datasets/delete/{label}

The query string is sent in the URL of the DELETE request. You need to pass the relevant label into the query string too.

Response Attributes

Response

{
    "responseHeader": {
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true
}

Returns a confirmation message that the Dataset was successfully deleted.

Attribute	Description
`success` Boolean	If `success` is true, the Dataset is successfully deleted. If `success` is false, it means that the query failed. If the Dataset doesn't exist, an error is returned.

Populating Datasets

Contrary to Screena One and Plus, Screena Firm uses a persistance layer.

Populating Datasets in Screena Firm is either synchronous or asynchronous and always require to extract, transform and load your own data sources and index them.

1. Extract data: In this stage, the data is collected, often from multiple and different types of sources. Whether your data is in a database, a collection of XML files, spreadsheets, or any other format, it doesn't matter to us. You must extract the data from your data sources and format it in a way that Screena recognizes. Concretely, you have to create Records with attributes. You don't need to extract everything. The process must be selective about what is in the file, gathering only information useful for building requests for matching or searching.

2. Transform data: You need to transform your extract from its previous form into a Screena-compatible format - JSON Records or Bulk Import, depending on the chosen method – either synchronous or asynchronous.

3. Load data: You need to load your Records into a Screena Repository, using our API.

This is all you need to start searching and matching your data.

Posting Records

This POST method allows to send one to many records into a Dataset in a single API call.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/post-records"

Endpoint: POST rest/v2/datasets/post-records

Individuals

Request: The following example shows how you can send a complex record via the API into a previously created Dataset. This example makes use of the synchronous capability of the application.

{
    "datasets": [{
            "label": "COMPANY 1",
            "records": [{
                "dataID": "15999",
                "entityType": "individual",
                "names": [{
                    "givenName": "John",
                    "surname": "Kennedy",
                    "motherName": "Fitzgerald"
                }, {
                    "fullName": "John Kennedy"
                }, {
                    "fullName": "JFK"
                }, {
                    "fullName": "Jack Kennedy"
                }],
                "sex": "M",
                "titles": [
                    "President of the United States"
                ],
                "keywords": [
                    "Deceased Politically Exposed Person"
                ],
                "sources": [
                    "https://en.wikipedia.org/wiki/John_F._Kennedy", "https://www.jfklibrary.org/"
                ],
                "nationalities": [{
                    "country": "US"
                }],
                "datesOfBirth": [{
                    "date": "1917-05-29"
                }],
                "placesOfBirth": [{
                    "city": "Brookline",
                    "state": "Massachusetts",
                    "country": "US"
                }],
                "addresses": [{
                    "street": "131 Cambridge St",
                    "zipCode": "MA 02114",
                    "city": "Boston",
                    "country": "US"
                }, {
                    "street": "1600 Pennsylvania Ave NW",
                    "zipCode": "DC 20500",
                    "city": "Washington",
                    "country": "US"
                }]
            }]
        },
        {
            "label": "COMPANY 2",
            "records": [{
                "dataID": "1",
                "entityType": "individual",
                "names": [{
                    "fullName": "Jean Marais"
                }],
                "sex": "M",
                "nationalities": [{
                    "country": "FR"
                }],
                "placesOfBirth": [{
                    "country": "FR"
                }]
            }]
        }
    ]
}

Attribute	Description	Required
`label` String	Unique Name of the Dataset that shall exist in the Screena Firm repository.	Yes
`records` Array of Data Objects	Set of source data used to populate the Dataset.	Yes
`dataID` String	Unique Identifier of the data record.	No
`entityType` String	Type of Named-Entities: shall be an individual. Refer to Named-Entities Objects for more info.	Yes individual
`names` Array of Name Objects	Name data in any and all scripts. At least one name attribute must be provided.	Yes
`givenName` String	Given Name.	No
`surname` String	Surname.	No
`fatherName` String	Father Name.	No
`motherName` String	Mother Name.	No
`fullName` String	Full Name.	No
`sex` String	Sex for an individual. Refer to Sexes and Genders for more info.	No
`nationalities` Array of Location Objects	Nationality for an individual, can be many. See child attributes for Countries.	No
`datesOfBirth` Array of Date Objects	Date of birth for an individual, can be many. Refer to Dates for more info.	No
`placesOfBirth` Array of Location Objects	Place of birth for an individual, can be many. See child Attributes for Places.	No
`addresses` Array of Location Objects	Address for an individual, can be many. See child Attributes for Addresses.	No
`titles` Array of Strings	Individual's position or job, can be many.	No
`keywords` Array of Strings	Word or phrase that is associated with a particular individual, organization or vessel and that describes information related to them. Typically in the context of Financial Crime Compliance, sanction regimes or law enforcement agencies’ programs (e.g., “Al-Qaida” or “White Collar Crimes”) are referred to as keywords.	No
`sources` Array of Strings	Any source from which information about the individual comes, arises, or is obtained.	No
`identityDocuments` Array of Identity Document Objects	Identity Document of an individual, can be many. See child attributes for Identity Documents.	No
`contactInformation` Array of Contact Information Objects	Contact information of an individual, can be many. See child attributes for Contact Information.	No
`digitalCurrencies` Array of Digital Currency Objects	Digital Currency related data, can be many. See child attributes for Digital Currencies.	No
`additionalInformation` Array of Strings	Additional information about an individual, can be many.	No
`active` Boolean	If `active` is true, the record is active and can be searched and matched upon. If `active` is false, the record is not accessible for matching and searching. If `active` is not provided, Screena will set the parameter at true.	No

Watch out — Do not use fullName with any other name attributes in the same block such as:

surname
givenName
fatherName
motherName

Only surname, givenName, fatherName, motherName can be used in the same block.

So, either you provide full names or parsed names in the same block but not both together. Otherwise, Screena will generate an error message.

Organizations

Attribute	Description	Required
`label` String	Unique Name of the Dataset that shall exist in the Screena Firm repository.	Yes
`records` Array of Data Objects	Set of source data used to populate the Dataset.	Yes
`dataID` String	Unique Identifier of the data record.	No
`entityType` String	Type of Named-Entities: shall be an organization. Refer to Named-Entities Objects for more info.	Yes organization
`names` Array of Name Objects	Name data in any and all scripts. At least one name attribute must be provided.	Yes
`fullName` String	Full Name.	No
`bic` String	Business Identifier Code (BIC) data to match (8-11 characters).	No
`lei` String	Legal Entity Identifier (LEI) data to match (20 characters).	No
`datesOfRegistry` Array of Date Objects	Date of registry for an organization, can be many. Refer to Dates for more info.	No
`placesOfRegistry` Array of Location Objects	Place of registry for an organization, can be many. See child Attributes for Places.	No
`addresses` Array of Location Objects	Address for an organization, can be many. See child Attributes for Addresses.	No
`keywords` Array of Strings	Word or phrase that is associated with a particular individual, organization or vessel and that describes information related to them. Typically in the context of Financial Crime Compliance, sanction regimes or law enforcement agencies’ programs (e.g., “Al-Qaida” or “White Collar Crimes”) are referred to as keywords.	No
`sources` Array of Strings	Any source from which information about the organization comes, arises, or is obtained.	No
`identityDocuments` Array of Identity Document Objects	Identity Document of an organization, can be many. See child attributes for Identity Documents.	No
`contactInformation` Array of Contact Information Objects	Contact information of an organization, can be many. See child attributes for Contact Information.	No
`digitalCurrencies` Array of Digital Currency Objects	Digital Currency related data, can be many. See child attributes for Digital Currencies.	No
`additionalInformation` Array of Strings	Additional information about an organization, can be many.	No
`active` Boolean	If `active` is true, the record is active and can be searched and matched upon. If `active` is false, the record is not accessible for matching and searching. If `active` is not provided, Screena will set the parameter at true.	No

Vessels

Attribute	Description	Required
`label` String	Unique Name of the Dataset that shall exist in the Screena Firm repository.	Yes
`records` Array of Data Objects	Set of source data used to populate the Dataset.	Yes
`dataID` String	Unique Identifier of the data record.	No
`entityType` String	Type of Named-Entities: shall be a vessel. Refer to Named-Entities Objects for more info.	Yes vessel
`names` Array of Name Objects	Name data in any and all scripts. At least one name attribute must be provided.	Yes
`fullName` String	Full Name	No
`flags` Array of Location Objects	Flags of vessel, can be many. See child attributes for Countries.	No
`datesOfBuild` Array of Date Objects	Date at which the vessel was completed, can be many. See child Attributes for Dates.	No
`keywords` Array of Strings	Word or phrase that is associated with a particular individual, organization or vessel and that describes information related to them. Typically in the context of Financial Crime Compliance, sanction regimes or law enforcement agencies’ programs (e.g., “Al-Qaida” or “White Collar Crimes”) are referred to as keywords.	No
`sources` Array of Strings	Any source from which information about the vessel comes, arises, or is obtained.	No
`additionalInformation` Array of Strings	Additional information about a vessel, can be many.	No
`identityDocuments` Array of Identity Document Objects	Identity Document related to a vessel, can be many. See child attributes for Identity Documents.	No
`active` Boolean	If `active` is true, the record is active and can be searched and matched upon. If `active` is false, the record is not accessible for matching and searching. If `active` is not provided, Screena will set the parameter at true.	No

Responses Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true,
    "processed": "2"
}

Returns a confirmation message that the Dataset was successfully populated.

Attribute	Description
`success` Boolean	If `success` is true, the Dataset is successfully populated with records. Otherwise an error is returned.
`processed` Integer	Total number of Records processed with which the Dataset has been populated.

Remember — The POST rest/v2/datasets/post-records method is applicable for record creation and update.

Dataset Bulk Importing

This POST method allows to start the bulk import of your data into Dataset.

This method makes use of multipart/form-data, which is one of the value of enctype attribute used in form elements that have a file upload. The multi-part means that the form data divides the file into multiple parts and sends it to the server.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: multipart/form-data" \
   -F 'upload_file=@/path/to/file' \
   "https://screena.ai/rest/v2/datasets/bulk-import"

Endpoint: POST rest/v2/datasets/bulk-import

Response Attributes

Response

{
    "responseHeader": {
        "responded": "2021-05-08T10:44:57.458Z"
    },
    "taskID": "TSK2054093905-1620470697458"
}

Returns a confirmation message that the asynchronous batch process was successfully started and a taskID is allocated.

How it works — The import is done through a file deposited in a directory accessible by Screena.

We recommend to use the JSON format, but CSV is also accepted by the application.

If you use the JSON format, there is nothing special to do, just specify the label of the Dataset where the records shall be imported as described in Posting Records.

For large volumes, an easier method is to upload a CSV file.

To import data into Screena using CSV files, you must respect our CSV file specifications, which are extremely flexible:

The CSV file shall be encoded in UTF-8.
The order of the fields in the CSV file is not important.
Unnecessary fields can be omitted in the CSV file.
Source or target Datasets shall be defined within the label field.
The delimiter between fields is the pipe.
It is possible to provide multiple values (name attributes, countries, dates, ...) in a field. The delimiter between multiple values is the semicolon.
It is possible to import subfields for fields like name or addresses.The delimiter between subfields is the tilt. The name of the fields is identical between JSON and CSV.

The below provide a CSV example:

label|dataID|entityType|name|sex|nationalities|datesOfBirth|datesOfRegistry|placesOfBirth|placesOfRegistry|addresses|additionalInformation|active
COMPANY 1|15999|individual|John~KENNEDY|M|US;FR|1917-05-29||Brookline~Massachusetts~US||Arlington~Virginia~US|private list|true
COMPANY 1|16000|organization|BCCI||||1972-01-01||luxembourg|luxembourg;uk;pakistan|private list|true
COMPANY 1|16001|vessel|RMS Titanic|||||||||true

For givenName, surname, fatherName, and motherName they shall be split by a tilt into the name field and provided into the right order. Similarly, unnecessary name elements can be omitted.

addresses subfields can be imported according to the following structure:

streetNumber~streetName~city~state~country
street~city~state~country
city~state~country
country

Unnecessary addresses subfields can be left empty. For example, if city and country subfields are provided without state, the addresses field can be imported as follow: Marseille~~FR

(In)activating Records

This POST method allows to manage the activation and inactivation of one to many records into a Dataset in a single API call. Inactivating Records removes Records from the matching process without having to permanently delete them.

This effectively means that at any time you can activate and reactivate relevant Records.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/edit-records"

Endpoint: POST rest/v2/datasets/edit-records

Request: The following example shows how you can inactivate Records via the API.

{
    "datasets": [{
        "label": "COMPANY 1",
        "records": [{
            "dataID": "15999",
            "active": false
        }, {
            "dataID": "169",
            "active": false
        }, {
            "dataID": "170",
            "active": false
        }]
    }]
}

Attribute	Description	Required
`label` String	Unique Name of the Dataset that shall exist in the Screena Firm repository.	Yes
`records` Array of Data Objects	Set of source data used to populate the Dataset.	Yes
`dataID` String	Unique Identifier of the data record.	No
`active` Boolean	If `active` is true, the record is active and can be searched and matched upon. If `active` is false, the record can't be matched or searched. If `active` is not provided, Screena will set the parameter at true.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true,
    "processed": "3"
}

Returns a confirmation message that the Record was successfully inactivated or reactivated.

Attribute	Description
`success` Boolean	If `success` is true, the Record is successfully inactivated/reactivated. Otherwise an error is returned.
`processed` String	Number or records that have been successfully processed (i.e. inactivated/activated).

Remember — If you want to inactivate or reactivate all the Records of a Dataset, simply set the Dataset active attribute at either true or false.

Browsing Records

This POST method allows to browse records in the Datasets created into the Screena Firm Repository.

You can use any of the below attributes independently or combined together to browse and filter the Records you need. Instead of fetching all the Records of a Dataset – which might take a long while or simply be irrelevant due to the volume at stake, you can directly browse one specific record through its dataID (in combinaison with its revision attribute if needed) or filter all the Records created within a specific day/time range.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   "https://screena.ai/rest/v2/datasets/browse-records"

Endpoint: POST rest/v2/datasets/browse-records

Request: If you would like to browse Records solely based on creation dates in a Dataset then you should do this.

{
    "datasets": [{
        "label": "COMPANY 1",
        "records": [{
            "created": "2020-01-01/2020-12-31"
        }]
    }]
}

Attribute	Description	Required
`label` String	Name of your Dataset as you specified it.	No
`created` String	Creation Date of the Record. Shall be provided in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.	No
`updated` String	Update Date of the Record. Shall be provided in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.	No
`category` String	Dataset category. It can be a watchlist, a grey list, a customer list, etc.	No
`lastMatched` String	Date/Time when the Record was last matched. This field is used to manage deltas in Delta Screening. Shall be provided in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.	No
`lastChecked`(Deprecated) String	Date/Time when the Record was last matched. This field is used to manage deltas in Delta Screening. Shall be provided in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.	No
`dataID` String	Unique Identifier of the data record.	No
`revision` Integer	Revision of the data Record, which keeps history of every change.	No

How it works — Every version of a Record is kept in memory and corresponds to a revision numeric value. Consequently, you can have access to any event affecting a Record including:

the current Revision (i.e. most recent published version),
any corrections or enhancements,
and any other changes made to the Record in question.

The first version of a Record is always numbered as Revision number 1.

Response Attributes

Returns the relevant Records further to the browsing request.

Individuals

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc27",
        "responded": "2021-04-17T14:30:15.321+01:00"
    },
    "datasets": [{
        "label": "COMPANY 1",
        "records": [{
            "dataID": "15999",
            "entityType": "individual",
            "names": [{
                "givenName": "John",
                "surname": "Kennedy",
                "motherName": "Fitzgerald"
            }, {
                "fullName": "John Kennedy"
            }, {
                "fullName": "JFK"
            }, {
                "fullName": "Jack Kennedy"
            }],
            "sex": "M",
            "nationalities": [{
                "country": "US"
            }],
            "datesOfBirth": [{
                "date": "1917-05-29"
            }],
            "placesOfBirth": [{
                "city": "Brookline",
                "state": "Massachusetts",
                "country": "US"
            }],
            "addresses": [{
                "street": "131 Cambridge St",
                "zipCode": "MA 02114",
                "city": "Boston",
                "country": "US"
            }, {
                "street": "1600 Pennsylvania Ave NW",
                "zipCode": "DC 20500",
                "city": "Washington",
                "country": "US"
            }],
            "categories": [
                "RETAIL"
            ],
            "active": true,
            "dataset": {
                "label": "COMPANY 1",
                "category": "CUSTOMER DATA"
            },
            "revision": 2,
            "created": "2020-04-17T14:30:15.321+01:00",
            "updated": "2020-04-21T17:33:25.441+01:00",
            "lastMatched": "2021-02-26T18:28:40.923"
        }]
    }]
}

Attribute	Description
`label` String	Name of your Dataset as you specified it.
`records` Array of Data Objects	Set of source data used to populate the Dataset.
`dataID` String	Unique Identifier of the data record.
`entityType` String	Type of Named-Entities: shall be an individual. Refer to Named-Entities Objects for more info.
`names` Array of Name Objects	Name data in any and all scripts. At least one name attribute must be provided.
`givenName` String	Given Name.
`surname` String	Surname.
`fatherName` String	Father Name.
`motherName` String	Mother Name.
`fullName` String	Full Name.
`sex` String	Sex for an individual. Refer to Sexes and Genders for more info.
`nationalities` Array of Location Objects	Nationality for an individual, can be many. See child attributes for Countries.
`datesOfBirth` Array of Date Objects	Date of birth for an individual, can be many. Refer to Dates for more info.
`placesOfBirth` Array of Location Objects	Place of birth for an individual, can be many. See child Attributes for Places.
`addresses` Array of Location Objects	Address for an individual, can be many. See child Attributes for Addresses.
`titles` Array of Strings	Individual's position or job, can be many.
`keywords` Array of Strings	Word or phrase that is associated with a particular individual, organization or vessel and that describes information related to them. Typically in the context of Financial Crime Compliance, sanction regimes or law enforcement agencies’ programs (e.g., “Al-Qaida” or “White Collar Crimes”) are referred to as keywords.
`sources` Array of Strings	Any source from which information about the individual comes, arises, or is obtained.
`identityDocuments` Array of Identity Document Objects	Identity Document of an individual, can be many. See child attributes for Identity Documents.
`contactInformation` Array of Contact Information Objects	Contact information of an individual, can be many. See child attributes for Contact Information.
`digitalCurrencies` Array of Digital Currency Objects	Digital Currency related data, can be many. See child attributes for Digital Currencies.
`additionalInformation` Array of Strings	Additional information about an individual, can be many.
`category`(Deprecated) String	Dataset category. It can be a watchlist, a grey list, a customer list, etc.
`categories`(New) Array of Strings	Class or division of individuals regarded as having particular shared characteristics, can be many.
`active` Boolean	If `active` is true, the record is active and can be searched and matched upon. If `active` is false, the record is not accessible for matching and searching.
`label`(Deprecated) Integer	Specific dataset's label from which the data record was retrieved.
`dataset`(New) Dataset Object	Specific dataset from which the data record was retrieved. See child attributes for Dataset.
`revision` Integer	Revision of the data record, which keeps history of every change.
`created` String	Creation Date/Time of the record. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`updated` String	Update Date/Time of the record. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`lastMatched` String	Date/Time when the Record was last matched. This field is used to manage deltas in Delta Screening. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`lastChecked`(Deprecated) String	Date/Time when the Record was last matched. This field is used to manage deltas in Delta Screening. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.

Organizations

Attribute	Description
`label` String	Name of your Dataset as you specified it.
`records` Array of Data Objects	Set of source data used to populate the Dataset.
`dataID` String	Unique Identifier of the data record.
`entityType` String	Type of Named-Entities: shall be an organization. Refer to Named-Entities Objects for more info.
`names` Array of Name Objects	Name data in any and all scripts. At least one name attribute must be provided.
`fullName` String	Full Name.
`bic` String	Business Identifier Code (BIC) data to match (8-11 characters).
`lei` String	Legal Entity Identifier (LEI) data to match (20 characters).
`datesOfRegistry` Array of Date Objects	Date of registry for an organization, can be many. Refer to Dates for more info.
`placesOfRegistry` Array of Location Objects	Place of registry for an organization, can be many. See child Attributes for Places.
`addresses` Array of Location Objects	Address for an organization, can be many. See child Attributes for Addresses.
`keywords` Array of Strings	Word or phrase that is associated with a particular individual, organization or vessel and that describes information related to them. Typically in the context of Financial Crime Compliance, sanction regimes or law enforcement agencies’ programs (e.g., “Al-Qaida” or “White Collar Crimes”) are referred to as keywords.
`sources` Array of Strings	Any source from which information about the organization comes, arises, or is obtained.
`identityDocuments` Array of Identity Document Objects	Identity Document of an organization, can be many. See child attributes for Identity Documents.
`contactInformation` Array of Contact Information Objects	Contact information of an organization, can be many. See child attributes for Contact Information.
`digitalCurrencies` Array of Digital Currency Objects	Digital Currency related data, can be many. See child attributes for Digital Currencies.
`additionalInformation` Array of Strings	Additional information about an organization, can be many.
`category`(Deprecated) String	Dataset category. It can be a watchlist, a grey list, a customer list, etc.
`categories`(New) Array of Strings	Class or division of organizations regarded as having particular shared characteristics, can be many.
`active` Boolean	If `active` is true, the record is active and can be searched and matched upon. If `active` is false, the record is not accessible for matching and searching.
`label`(Deprecated) Integer	Specific dataset's label from which the data record was retrieved.
`dataset`(New) Dataset Object	Specific dataset from which the data record was retrieved. See child attributes for Dataset.
`revision` Integer	Revision of the data record, which keeps history of every change.
`created` String	Creation Date/Time of the record. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`updated` String	Update Date/Time of the record. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`lastMatched` String	Date/Time when the Record was last matched. This field is used to manage deltas in Delta Screening. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`lastChecked`(Deprecated) String	Date/Time when the Record was last matched. This field is used to manage deltas in Delta Screening. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.

Watch out — The next version of our software will support multiple values for all data fields, including placesOfRegistry, datesOfRegistry, datesOfIssue, and datesOfExpiry. However, it is important to note that this version does not yet support arrays that can store multiple values for these fields. Currently, the software can only store a single value for each of these fields in the format of placeOfRegistry, dateOfRegistry, dateOfIssue, and dateOfExpiry.

Vessels

Attribute	Description
`label` String	Name of your Dataset as you specified it.
`records` Array of Data Objects	Set of source data used to populate the Dataset.
`dataID` String	Unique Identifier of the data record.
`entityType` String	Type of Named-Entities: shall be a vessel. Refer to Named-Entities Objects for more info.
`names` Array of Name Objects	Name data in any and all scripts. At least one name attribute must be provided.
`fullName` String	Full Name.
`flags` Array of Location Objects	Flags of vessel, can be many. See child attributes for Countries.
`datesOfBuild` Array of Date Objects	Date at which the vessel was completed, can be many. See child Attributes for Dates.
`keywords` Array of Strings	Word or phrase that is associated with a particular individual, organization or vessel and that describes information related to them. Typically in the context of Financial Crime Compliance, sanction regimes or law enforcement agencies’ programs (e.g., “Al-Qaida” or “White Collar Crimes”) are referred to as keywords.
`identityDocuments` Array of Identity Document Objects	Identity Document of a vessel, can be many. See child attributes for Identity Documents.
`sources` Array of Strings	Any source from which information about the vessel comes, arises, or is obtained.
`additionalInformation` Array of Strings	Additional information about a vessel, can be many.
`category`(Deprecated) String	Dataset category. It can be a watchlist, a grey list, a customer list, etc.
`categories` Array of Strings	Class or division of individuals regarded as having particular shared characteristics, can be many.
`active` Boolean	If `active` is true, the record is active and can be searched and matched upon. If `active` is false, the record is not accessible for matching and searching.
`label`(Deprecated) Integer	Specific dataset's label from which the data record was retrieved.
`dataset`(New) Dataset Object	Specific dataset from which the data record was retrieved. See child attributes for Dataset.
`revision` Integer	Revision of the data record, which keeps history of every change.
`created` String	Creation Date/Time of the record. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`updated` String	Update Date/Time of the record. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`lastMatched` String	Date/Time when the Record was last matched. This field is used to manage deltas in Delta Screening. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
`lastChecked`(Deprecated) String	Date/Time when the Record was last matched. This field is used to manage deltas in Delta Screening. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.

Deleting Records

This DELETE method allows to delete records created within Datasets. Contrary to an inactivation, this method ensures hard deletion.

Request Attributes

curl -s -X DELETE \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   "https://screena.ai/rest/v2/records/456"

Endpoint: DELETE rest/v2/datasets/delete/{label}/record/{dataID}

The query string is sent in the URL of the DELETE request. You need to pass the relevant label and dataID into the query string too.

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true
}

Returns a confirmation message that the Record was successfully deleted.

Attribute	Description
`success` Boolean	If `success` is true, the Record is successfully created. Otherwise an error is returned.

Watch out — A hard delete, permanent deletion, complete erasure can be sometimes required. Contrary to inactivation, a deletion permanently deletes the relevant record(s). It is possible to hard delete any and all data from Screena databases.

Also known as the right to erasure, the General Data Protection Regulation (GDPR) gives citizens the right to ask organizations to delete their personal data. Data purged in a hard delete is unrecoverable and allows a person to be "forgotten" completely, and consequently comply with GDPR requirements.

"Don't it always seem to go / That you don't know what you've got / Till it's gone" – Once a record is gone, it’s gone. We advise that you use this method only when absolutely needed. If you are not sure, remember you can always chose the (In)activate Records method.

Searching Datasets

Designed for data searching named-entities with large sets of data, Screena Firm was engineered taking into account the possibility of having multiple Datasets.

This POST method allows to send one to many search queries in a single API call, it executes a search of all Named-Entities in sourceData against all Datasets in targetData.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/dataset-search"

Endpoint: POST rest/v2/dataset-search

Request

{
    "queries": [{
        "sourceData": [{
            "entityType": "individual",
            "names": [{
                "givenName": "john",
                "surname": "kennedi"
            }],
            "addresses": [{
                "country": "US"
            }]
        }],
        "targetData": [{
            "datasets": [{
                    "label": "COMPANY 1"
                },
                {
                    "label": "COMPANY 2"
                }
            ]
        }],
        "threshold": 0.82,
        "addressAlgo": {
            "type": "same_region"
        }
    }]
}

Attribute	What can be used ?	Required
`sourceData` Array of Data Objects	Use All the Request Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching MRTD Matching Narratives Matching Identity Documents Matching BICs Matching LEIs	Yes
`targetData` Array of Data Objects	Use `label` in `targetData` to search within particular Dataset(s).	No
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No
`-`	All available algorithms. Refer to Algorithms for more information.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "GEN2054093905-1620722489823",
        "responded": "2021-05-11T08:41:29.823Z"
    },
    "results": [{
            "matchType": "ai_accept",
            "score": 0.84,
            "sourceData": [{
                "entityType": "individual",
                "names": [{
                    "surname": "kennedi",
                    "givenName": "john",
                    "normalized": "john kennedi"
                }],
                "cultureCodes": [
                    "en"
                ],
                "addresses": [{
                        "country": "US",
                        "normalized": "AMERICAS"
                    },
                    {
                        "country": "US",
                        "normalized": "AMERICAS"
                    }
                ]
            }],
            "targetData": [{
                "dataID": "15999",
                "entityType": "unknown",
                "names": [{
                    "surname": "Kennedy",
                    "givenName": "John",
                    "motherName": "Fitzgerald",
                    "normalized": "john fitzgerald kennedy"
                }],
                "cultureCodes": [
                    "cy",
                    "en",
                    "ga"
                ],
                "addresses": [{
                        "street": "131 Cambridge St",
                        "city": "Boston",
                        "country": "US",
                        "zipCode": "MA 02114",
                        "normalized": "AMERICAS"
                    },
                    {
                        "street": "1600 Pennsylvania Ave NW",
                        "city": "Washington",
                        "country": "US",
                        "zipCode": "DC 20500",
                        "normalized": "AMERICAS"
                    }
                ],
                "dataset": {
                    "label": "COMPANY 1",
                    "category": "CUSTOMER DATA"
                }
            }]
        },
        {
            "matchType": "st_match",
            "score": 0.98,
            "sourceData": [{
                "entityType": "individual",
                "names": [{
                    "surname": "kennedi",
                    "givenName": "john",
                    "normalized": "john kennedi"
                }],
                "cultureCodes": [
                    "en"
                ],
                "addresses": [{
                        "country": "US",
                        "normalized": "AMERICAS"
                    },
                    {
                        "country": "US",
                        "normalized": "AMERICAS"
                    }
                ]
            }],
            "targetData": [{
                "dataID": "15999",
                "entityType": "unknown",
                "names": [{
                    "fullName": "John Kennedy",
                    "normalized": "john kennedy"
                }],
                "cultureCodes": [
                    "cy",
                    "en",
                    "ga"
                ],
                "addresses": [{
                        "street": "131 Cambridge St",
                        "city": "Boston",
                        "country": "US",
                        "zipCode": "MA 02114",
                        "normalized": "AMERICAS"
                    },
                    {
                        "street": "1600 Pennsylvania Ave NW",
                        "city": "Washington",
                        "country": "US",
                        "zipCode": "DC 20500",
                        "normalized": "AMERICAS"
                    }
                ],
                "dataset": {
                    "label": "COMPANY 1",
                    "category": "CUSTOMER DATA"
                }
            }]
        }
    ]
}

Attribute	What is returned ?
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. AI scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`sourceData` Array of Data Objects	Get the same Response Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching Narratives Matching Identity Documents Matching BICs Matching LEIs
`targetData` Array of Data Objects	Get the same Response Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching Narratives information about the relevant Datasets in which a match was found like in Browsing Records

Exporting Search Reports

Exporting Search Reports is a feature designed for data searching named-entities with large sets of data and obtaining the results of the search in the form of PDF or CSV report.

When using the dataset search capability, users may need to extract search results to share or analyze data outside of the search engine. The exporting reports feature allows users to export the search results in the form of a PDF or CSV report, making it easy to share and analyze data with others.This feature is also especially useful for preserving a proof of a search at a particular time.

This POST method allows to send one to many search queries in a single API call, it executes a search of all Named-Entities in sourceData against all Datasets in targetData.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets//dataset-search-engine-export"

Endpoints: POST rest/v2/dataset-search-engine-export and POST rest/v2/dataset-search-engine-export-pdf

Request

{
    "queries": [{
        "sourceData": [{
            "entityType": "individual",
            "names": [{
                "givenName": "vladimir",
                "surname": "Putin"
            }],
            "addresses": [{
                "country": "RU"
            }]
        }],
        "targetData": [{
            "datasets": [{
                    "label": "EU"
                },
                {
                    "label": "OFAC"
                }
            ]
        }],
        "threshold": 0.80,
        "addressAlgo": {
            "type": "same_region"
        }
    }]
}

Attribute	What can be used ?	Required
`sourceData` Array of Data Objects	Use All the Request Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching MRTD Matching Narratives	Yes
`targetData` Array of Data Objects	Use `label` in `targetData` to search within particular Dataset(s).	No
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No
`-`	All available algorithms. Refer to Algorithms for more information.	No

Response Attributes

When a request is made, the resulting output is provided in the form of either a PDF or CSV file. These files contain comprehensive information about the source and target data.

Integrating Watchlist Screening

Screena is designed to integrate with watchlists and third-party risk intelligence for named-entity screening.

This POST method provides additional features compared to the regular Searching Datasets method, including:

Pagination: Divides returned content across a series of pages. It is a common and widely used technique for websites to use pagination to divide returned results into a digestible format.
Statistics: Returns statistics on search terms.
Matching Names: Gives the exact matching name that correlates with the searched one.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/dataset-search-engine"

Endpoint: POST rest/v2/dataset-search-engine

Request: Search by Name

{
    "queries": [{
        "sourceData": [{
            "names": [{
                "fullName": "emmanuel macron"
            }]
        }],
        "targetData": [{
            "datasets": [{
                    "label": "EU"
                },
                {
                    "label": "WORLD LEADERS"
                }
            ]
        }],
        "threshold": 0.57
    }],
    "paginationRequest": {
        "pageNumber": 0,
        "maxPerPage": 2,
        "calculateSearchStats": true
    }
}

Request: Search by Identity Document

{
    "queries": [{
        "sourceData": [{
            "identityDocuments": [{
                "number": "7722437025"
            }]
        }],
        "targetData": [{
            "datasets": [{
                "label": "USA"
            }]
        }],
        "identityDocumentAlgo": {
            "type": "exact_match"
        }
    }]
}

Request: Search by BIC

{
    "queries": [{
        "sourceData": [{
            "bic": "SABRRUMM"
        }],
        "targetData": [{
            "datasets": [{
                "label": "USA"
            }]
        }],
        "bicAlgo": {
            "type": "exact_match"
        }
    }]
}

Request: Search by LEI

{
    "queries": [{
        "sourceData": [{
            "lei": "25340038P8SYW80B9W34"
        }],
        "targetData": [{
            "datasets": [{
                "label": "USA"
            }]
        }],
        "leiAlgo": {
            "type": "exact_match"
        }
    }]
}

Attribute	What can be used ?	Required
`sourceData` Array of Data Objects	Use All the Request Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching MRTD Matching Narratives	Yes
`targetData` Array of Data Objects	Use `label` in `targetData` to search within particular Dataset(s).	No
`paginationRequest` Array of Pagination Objects	Divide search results into several pages.	No
`pageNumber` Integer	Number of the page to be returned.	No
`maxPerPage` Integer	Maximum number of results provided per page.	No
`calculateSearchStats` Boolean	Calculate statistics on the returned search results.	No
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No
`-`	All available algorithms. Refer to Algorithms for more information.	No

Remember — Customers operating in a multi-tenancy environment can use label to determine which Dataset(s) they want to search upon. Every query sent for identity verification purposes can target multiple independent Datasets and use different threshold and algorithmic parameters.

In a Financial Crime Compliance context, Datasets can be populated with watchlists and third-party risk intelligence. Screena supports the integration with public and proprietary watchlists, including those embedded into Screena's online Instant Search. Refer to Watchlists for more information.

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "GEN2054093905-1678608268248",
        "responded": "2023-03-12T08:04:28.248Z"
    },
    "results": [{
            "matchType": "st_match",
            "score": 1.00,
            "matchingNames": [{
                "fullName": "Emmanuel MACRON",
                "normalized": "emmanuel macron"
            }],
            "sourceData": [{
                "entityType": "unknown",
                "names": [{
                    "fullName": "emmanuel macron",
                    "normalized": "emmanuel macron"
                }],
                "cultureCodes": [
                    "en",
                    "fr"
                ]
            }],
            "targetData": [{
                "dataID": "AD-245342216",
                "entityType": "individual",
                "names": [{
                    "fullName": "Emmanuel MACRON",
                    "normalized": "emmanuel macron"
                }],
                "cultureCodes": [
                    "en",
                    "fr"
                ],
                "nationalities": [{
                    "country": "AD"
                }],
                "categories": [
                    "PEP"
                ],
                "active": true,
                "sources": [
                    "https://www.cia.gov/resources/government/andorra/"
                ],
                "titles": [
                    "Head of State (Co-Prince)"
                ],
                "dataset": {
                    "label": "WORLD LEADERS",
                    "category": "PEP",
                    "dateOfUpload": "2023-03-12T00:45:32.713"
                },
                "lastMatched": "2023-02-08T00:45:00.698",
                "lastChecked": "2023-02-08T00:45:00.698"
            }]
        },
        {
            "matchType": "st_match",
            "score": 1.00,
            "matchingNames": [{
                "fullName": "Emmanuel MACRON",
                "normalized": "emmanuel macron"
            }],
            "sourceData": [{
                "entityType": "unknown",
                "names": [{
                    "fullName": "emmanuel macron",
                    "normalized": "emmanuel macron"
                }],
                "cultureCodes": [
                    "en",
                    "fr"
                ]
            }],
            "targetData": [{
                "dataID": "FR-245342216",
                "entityType": "individual",
                "names": [{
                    "fullName": "Emmanuel MACRON",
                    "normalized": "emmanuel macron"
                }],
                "cultureCodes": [
                    "en",
                    "fr"
                ],
                "nationalities": [{
                    "country": "FR"
                }],
                "categories": [
                    "PEP"
                ],
                "active": true,
                "sources": [
                    "https://www.cia.gov/resources/government/france/"
                ],
                "titles": [
                    "Pres."
                ],
                "dataset": {
                    "label": "WORLD LEADERS",
                    "category": "PEP",
                    "dateOfUpload": "2023-03-12T00:45:32.713"
                },
                "lastMatched": "2023-02-08T00:45:32.594",
                "lastChecked": "2023-02-08T00:45:32.594"
            }]
        }
    ],
    "numberOfObjects": 2,
    "searchStats": {
        "numberOfPeps": 2,
        "numberOfSanctions": 0,
        "numberOfWanteds": 0,
        "numberOfAll": 2,
        "numberOfOrganizations": 0,
        "numberOfIndividuals": 2,
        "numberOfUnknowns": 0,
        "numberOfVessels": 0,
        "foundDataset": [
            "WORLD LEADERS"
        ]
    }
}

Attribute	What is returned ?
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. AI scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`matchingNames` Array of Name Objects	Get the names that have matched your query.
`sourceData` Array of Data Objects	Get the same Response Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching Narratives
`targetData` Array of Data Objects	Get the same Response Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching Narratives information about the relevant Datasets in which a match was found like in Browsing Records
`numberOfObjects` Integer	Total number of objects returned by the search.
`searchStats` Statistic Object	Get statistical information about your data, which can vary depending on the use case.

Periodic Screening

Endpoint: POST rest/v2/dataset-search-engine-ongoing

The purpose of creating a dedicated endpoint for Periodic Screening of relevant watchlists (a.k.a. Ongoing Screening, Ongoing Due Diligence, Continuous Screening) is to separate it from one-time event-driven watchlist screening, which is closely associated with customer onboarding or payment processing.

This segregation is important because Periodic Screening typically involves a higher volume of transactions in batch. By segregating the two, the endpoint can be optimized for the specific needs of each type of screening, resulting in better overall performance.

It is worth noting that the functioning of this endpoint is similar to Integrating Watchlist Screening: the endpoint for Periodic Screening is simply designed to handle the unique requirements of Periodic Screening of watchlists and is optimized accordingly.

Matching Datasets

Designed for matching 2 or more large Datasets, this method executes a search of all Datasets specified in sourceData against all Datasets specified in targetData in a single API call.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/dataset-match"

Endpoint: POST rest/v2/dataset-match

Request

{
    "requestHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc35"
    },
    "queries": [{
        "sourceData": [{
            "datasets": [{
                "label": "COMPANY 1"
            }]
        }],
        "targetData": [{
            "datasets": [{
                "label": "WATCHLIST 1"
            }, {
                "label": "WATCHLIST 2"
            }]
        }]
    }],
    "threshold": 0.90,
    "nationalityAlgo": {
        "type": "same_country"
    },
    "dateOfBirthAlgo": {
        "type": "same_day_month_year"
    },
    "placeOfBirthAlgo": {
        "type": "same_country"
    },
    "addressAlgo": {
        "type": "same_region"
    }
}

Attribute	What can be used ?	Required
`sourceData` Array of Data Objects	Use `label` in `sourceData` to select one or many specific Datasets to run the match query from.	Yes
`targetData` Array of Data Objects	Use `label` in `targetData` to select one or many specific Datasets to run the match query against.	Yes
`threshold` Decimal	The AI match threshold is the probability represented by a value from 0 to 1 at which the user decides it is deemed certain that a record is similar to another one. If this parameter is not provided, Screena will apply a default threshold value set at 0.60. Refer to Name-Matching Algorithms for more info.	No
`-`	All available algorithms. Refer to Algorithms for more information.	No

Response Attributes

Response

{
    "responseHeader": {
        "responded": "2021-05-08T10:44:57.458Z"
    },
    "taskID": "TSK2054093905-1620487949689"
}

Returns a confirmation message that the asynchronous batch process was successfully started and a taskID is allocated.

By using the provided taskID it is possible to know the progress of a task. Refer to Asynchronous Tasks for more details.

Performance — Due to potentially high volumes at stake, it's important to note the following:

Matching performance does not scale linearly. A dataset twice as large as another one does not take twice as long to process.
It is possible to determine what a Task's duration could be in practice, but you need to first understand how many combinations are possible. The point, in practice, is therefore to carefully consider those possible combinations and take this into account when matching data from large Datasets.
By default, "no_match" and "ai_reject" are not returned into Match Results, as otherwise data size and performance would become unmanageable.
Screena performance is impacted by hardware characteristics including CPU, cache and memory performance.

Our experts are available to answer your technical questions about Screena Firm tuning and help you find the solution you need. Drop us an email: experts@screena.ai

Getting Match Results

As the process of matching 2 Datasets is asynchronous, you shall use a taskID to retrieve the results.

The total population of Results can be split into:

those being predicted as positives ("st_match" and "ai_accept"), and
those being predicted as negatives ("no_match and ai_reject").

Three Endpoints are provided allowing to retrieve the match results suited to your needs:

Full results (i.e. results predicted as positives as well as resultats predicted as negatives).
Results predicted as positives.
Results predicted as negatives.

Request Attributes

curl -s -X GET \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   "https://screena.ai/rest/v2/dataset-match/c779f2c29b054066b6c03d4da903dc35"

Endpoints:

GET rest/v2/dataset-match/{taskID} : Getting full Results.
GET rest/v2/dataset-match/positives/{taskID} : Getting Results predicted as positives.
GET rest/v2/dataset-match/negatives/{taskID} : Getting Results predicted as negatives.

The query string is sent in the URL of the GET request. You need to pass the relevant taskID into the query string too.

Response Attributes

Result

{
    "responseHeader": {
        "responded": "2021-04-25T17:42:41.829Z",
        "taskID": "TSK2054093905-1619372310206"
    },
    "results": [{
        "matchType": "ai_reject",
        "score": 0.02,
        "sourceData": [{
            "dataID": "110406",
            "entityType": "unknown",
            "names": [{
                "fullName": "Aali Akber Tahmaesebi",
                "normalized": "aali akber tahmaesebi"
            }],
            "cultureCodes": ["ar"],
            "active": true,
            "dataset": {
                "label": "thoughtbox-source"
            },
            "revision": 1,
            "created": "2021-04-25T17:38:31.497",
            "updated": "2021-04-25T17:38:31.497",
            "lastMatched": "2021-02-26T10:39:39.852"
        }],
        "targetData": [{
            "dataID": "6696",
            "entityType": "individual",
            "names": [{
                "surname": "Tahmaesebi",
                "givenName": "Sayed",
                "fatherName": "Akbar",
                "normalized": "sayed akbar tahmaesebi"
            }],
            "cultureCodes": ["bn", "pa", "ur"],
            "active": true,
            "dataset": {
                "label": "EU",
                "category": "SANCTION",
                "dateOfPublication": "2023-05-02T00:00:00",
                "dateOfUpload": "2023-05-09T08:10:29.172"
            },
            "revision": 1,
            "created": "2021-04-25T17:38:31.497",
            "updated": "2021-04-25T17:38:31.497",
            "lastMatched": "2021-02-28T09:00:26.341"
        }]
    }]
}

Attribute	What is returned ?
`matchType` String	Type of the match result. Refer to Name-match Types for more info.
`score` Decimal	Name matching probability score: A high value of this score is a strong indication of a good name similarity. AI scores below the threshold value provided in the request are rejected. Refer to Name-Matching Algorithms for more info.
`sourceData` Array of Data Objects	Get the same Response Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching Narratives information about the relevant Datasets in which a match was found like in Browsing Records
`targetData` Array of Data Objects	Get the same Response Attributes that are available in Screena Plus: Matching Individuals Matching Organizations Matching Vessels Matching Narratives information about the relevant Datasets in which a match was found like in Browsing Records

About Delta Screening

Where either source or target Datasets change frequently, Delta Screening may be required.

Screena's Delta Screening feature avoids to periodically regenerate the same results. Once the full source Dataset has been screened against the full target Dataset, only deltas are considered.

The below lists all possible deltas:

A new source record is a delta, and is matched against all target records.
A new target record is a delta, and is matched against all source records.
A change in a source record attribute is a delta. When it occurs the record is matched against all target records.
A change in a target record attribute is a delta. When it occurs the record is matched against all source records.

High-Risk Locations

High-risk locations are typically:

countries with significant gaps in their countermeasures against financial crime,
countries with significant level of corruption,
countries designed as such by international bodies such as the financial work force (FATF),
places where there is a particularly significant risk of funding crime and/or terrorism,
places with high crime rates.

Screena proposes a solution to minimize the effort relating to the detection of the occurrence of high-risk locations in data related to named-entities.

For convenience, there is no specific endpoint for high-risk locations detection. This feature accompanies the advanced name-screening features as provided in Screena Firm Searching Datasets as well as Integrating Watchlist Screening and usefully completes them.

Structured Addresses

Addresses which are structured by their individual components (e.g, country, postal code, city, street number) are the type of data in which it is the easiest to find the occurrence of a high-risk location.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/dataset-search"

Endpoint: POST rest/v2/dataset-search

For a comprehensive list of attributes that can be used, refer to Screena Firm Searching Datasets.

Request

{
    "queries": [{
        "sourceData": [{
            "names": [{
                "fullName": "Satuev Magomed"
            }],
            "addresses": [{
                "city": "Raqqah",
                "country": "SY"
            }]
        }],
        "targetData": [{
            "datasets": [{
                "label": "INTERPOL"
            }]
        }],
        "threshold": 0.90
    }]
}

Response Attributes

For a complete list of attributes that are returned, refer to Screena Firm Searching Datasets. In addition to these attributes, you will obtain the specific attributes relating to the detection of high-risk location.

On top of other information, it returns an array of matchingCountries.

Attribute	What is returned ?
`country` String	Country matching with a high-risk location.
`ctrp` String	Cities, Towns, Regions & Ports matching with a high-risk location.
`risk` String	Risk related to the detected high-risk location.

Response

{
    "responseHeader": {
        "requestID": "GEN2054093905-1703152291777",
        "responded": "2023-12-21T09:51:31.777Z"
    },
    "results": [
        {
            "matchType": "st_match",
            "score": 0.98,
            "matchingNames": [
                {
                    "surname": "SATUEV",
                    "givenName": "MAGOMED",
                    "normalized": "magomed satuev"
                }
            ],
            "sourceData": [
                {
                    "entityType": "unknown",
                    "names": [
                        {
                            "fullName": "Satuev Magomed",
                            "normalized": "satuev magomed"
                        }
                    ],
                    "cultureCodes": [
                        "ru"
                    ]
                }
            ],
            "targetData": [
                {
                    "dataID": "2021/70850",
                    "entityType": "individual",
                    "names": [
                        {
                            "surname": "SATUEV",
                            "givenName": "MAGOMED",
                            "normalized": "magomed satuev"
                        }
                    ],
                    "cultureCodes": [
                        "ru"
                    ],
                    "nationalities": [
                        {
                            "country": "RU"
                        }
                    ],
                    "datesOfBirth": [
                        {
                            "date": "1983-05-14"
                        }
                    ],
                    "placesOfBirth": [
                        {
                            "city": "LENINAUL VILLAGE (THE REPUBLIC OF DAGESTAN)",
                            "country": "RU"
                        }
                    ],
                    "additionalInformation": [
                        "participation in the activity of a terrorist organization; participation in the activity of an illegal armed formation"
                    ],
                    "categories": [
                        "WANTED"
                    ],
                    "active": true,
                    "keywords": [
                        "Red Notice"
                    ],
                    "sources": [
                        "https://ws-public.interpol.int/notices/v1/red/2021-70850"
                    ],
                    "label": "INTERPOL",
                    "dataset": {
                        "label": "INTERPOL",
                        "category": "WANTED",
                        "dateOfUpload": "2023-12-21T00:41:39.531"
                    },
                    "lastMatched": "2023-02-08T00:48:14.844",
                    "lastChecked": "2023-02-08T00:48:14.844"
                }
            ]
        },
        {
            "matchingCountries": [
                {
                    "country": "SY",
                    "risk": "Blacklisted Country (Syria)"
                },
                {
                    "country": "SY",
                    "ctrp": "raqqah",
                    "risk": "Blacklisted CTRP (Syria)"
                }
            ],
            "sourceData": [
                {
                    "entityType": "unknown",
                    "addresses": [
                        {
                            "city": "Raqqah",
                            "country": "SY"
                        }
                    ]
                }
            ]
        }
    ]
}

Freeform Addresses

The addresses in freeform are a challenge because its latest submitting the whole address in a single field. This method is not recommended when it is possible to provide the structured address.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/dataset-search"

Endpoint: POST rest/v2/dataset-search

Request

{
    "queries": [{
        "sourceData": [{
            "names": [{
                "fullName": "Satuev Magomed"
            }],
            "addresses": [{
                "fullAddress": "Somewhere in Raqqah"
            }]
        }],
        "targetData": [{
            "datasets": [{
                "label": "INTERPOL"
            }]
        }],
        "threshold": 0.90
    }]
}

Response Attributes

On top of other information, it returns an array of matchingCountries.

Attribute	What is returned ?
`country` String	Country matching with a high-risk location.
`ctrp` String	Cities, Towns, Regions & Ports matching with a high-risk location.
`risk` String	Risk related to the detected high-risk location.

Response

{
    "responseHeader": {
        "requestID": "GEN2054093905-1703152440605",
        "responded": "2023-12-21T09:54:00.605Z"
    },
    "results": [
        {
            "matchType": "st_match",
            "score": 0.98,
            "matchingNames": [
                {
                    "surname": "SATUEV",
                    "givenName": "MAGOMED",
                    "normalized": "magomed satuev"
                }
            ],
            "sourceData": [
                {
                    "entityType": "unknown",
                    "names": [
                        {
                            "fullName": "Satuev Magomed",
                            "normalized": "satuev magomed"
                        }
                    ],
                    "cultureCodes": [
                        "ru"
                    ]
                }
            ],
            "targetData": [
                {
                    "dataID": "2021/70850",
                    "entityType": "individual",
                    "names": [
                        {
                            "surname": "SATUEV",
                            "givenName": "MAGOMED",
                            "normalized": "magomed satuev"
                        }
                    ],
                    "cultureCodes": [
                        "ru"
                    ],
                    "nationalities": [
                        {
                            "country": "RU"
                        }
                    ],
                    "datesOfBirth": [
                        {
                            "date": "1983-05-14"
                        }
                    ],
                    "placesOfBirth": [
                        {
                            "city": "LENINAUL VILLAGE (THE REPUBLIC OF DAGESTAN)",
                            "country": "RU"
                        }
                    ],
                    "additionalInformation": [
                        "participation in the activity of a terrorist organization; participation in the activity of an illegal armed formation"
                    ],
                    "categories": [
                        "WANTED"
                    ],
                    "active": true,
                    "keywords": [
                        "Red Notice"
                    ],
                    "sources": [
                        "https://ws-public.interpol.int/notices/v1/red/2021-70850"
                    ],
                    "label": "INTERPOL",
                    "dataset": {
                        "label": "INTERPOL",
                        "category": "WANTED",
                        "dateOfUpload": "2023-12-21T00:41:39.531"
                    },
                    "lastMatched": "2023-02-08T00:48:14.844",
                    "lastChecked": "2023-02-08T00:48:14.844"
                }
            ]
        },
        {
            "matchingCountries": [
                {
                    "country": "SY",
                    "risk": "Blacklisted Country (Syria)"
                },
                {
                    "country": "SY",
                    "ctrp": "raqqah",
                    "risk": "Blacklisted CTRP (Syria)"
                }
            ],
            "sourceData": [
                {
                    "entityType": "unknown",
                    "addresses": [
                        {
                            "country": "SY",
                            "fullAddress": "raqqah"
                        }
                    ]
                }
            ]
        }
    ]
}

Narratives

Finding the presence of geographic information in narratives is mainly used in the field of the transaction screening in order to ensure that no indicia that can suggest a transaction with a high-risk country can occur. This is a regulatory constraint imposed on financial institutions. Screena provides this functional capacity by using artificial intelligence to analyze unstructured data in the form of free text.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/dataset-search"

Endpoint: POST rest/v2/dataset-search

Request

{
    "queries": [{
        "sourceData": [{
            "narrative": "Satuev Magomed, Labuan, Malaysia"
        }],
        "targetData": [{
            "datasets": [{
                "label": "INTERPOL"
            }]
        }],
        "threshold": 0.90
    }]
}

Response Attributes

On top of other information, it returns an array of matchingCountries.

Attribute	What is returned ?
`country` String	Country matching with a high-risk location.
`ctrp` String	Cities, Towns, Regions & Ports matching with a high-risk location.
`risk` String	Risk related to the detected high-risk location.

Response

{
    "responseHeader": {
        "requestID": "GEN2054093905-1703152524688",
        "responded": "2023-12-21T09:55:24.688Z"
    },
    "results": [
        {
            "matchType": "st_match",
            "score": 0.98,
            "matchingNames": [
                {
                    "surname": "SATUEV",
                    "givenName": "MAGOMED",
                    "normalized": "magomed satuev"
                }
            ],
            "sourceData": [
                {
                    "entityType": "unknown",
                    "names": [
                        {
                            "fullName": "satuev magomed",
                            "normalized": "satuev magomed"
                        }
                    ],
                    "cultureCodes": [
                        "ru"
                    ],
                    "narrative": "Satuev Magomed, Labuan, Malaysia"
                }
            ],
            "targetData": [
                {
                    "dataID": "2021/70850",
                    "entityType": "individual",
                    "names": [
                        {
                            "surname": "SATUEV",
                            "givenName": "MAGOMED",
                            "normalized": "magomed satuev"
                        }
                    ],
                    "cultureCodes": [
                        "ru"
                    ],
                    "nationalities": [
                        {
                            "country": "RU"
                        }
                    ],
                    "datesOfBirth": [
                        {
                            "date": "1983-05-14"
                        }
                    ],
                    "placesOfBirth": [
                        {
                            "city": "LENINAUL VILLAGE (THE REPUBLIC OF DAGESTAN)",
                            "country": "RU"
                        }
                    ],
                    "additionalInformation": [
                        "participation in the activity of a terrorist organization; participation in the activity of an illegal armed formation"
                    ],
                    "categories": [
                        "WANTED"
                    ],
                    "active": true,
                    "keywords": [
                        "Red Notice"
                    ],
                    "sources": [
                        "https://ws-public.interpol.int/notices/v1/red/2021-70850"
                    ],
                    "label": "INTERPOL",
                    "dataset": {
                        "label": "INTERPOL",
                        "category": "WANTED",
                        "dateOfUpload": "2023-12-21T00:41:39.531"
                    },
                    "lastMatched": "2023-02-08T00:48:14.844",
                    "lastChecked": "2023-02-08T00:48:14.844"
                }
            ]
        },
        {
            "matchingCountries": [
                {
                    "ctrp": "labuan",
                    "risk": "Blacklisted CTRP (Labuan)"
                }
            ],
            "sourceData": [
                {
                    "entityType": "unknown",
                    "addresses": [
                        {
                            "country": "MY",
                            "fullAddress": "labuan"
                        }
                    ],
                    "narrative": "Satuev Magomed, Labuan, Malaysia"
                }
            ]
        }
    ]
}

SWIFT/BICs

SWIFT operates the series of electronic messages that are sent between financial institutions (FIs) to facilitate the transfer of funds. A Bank Identification code or BIC Code, is assigned by SWIFT to financial institutions to identify them unequivocally. The BIC Code is an 8-11 character code that specifies financial institutions' country, city, bank, and branch. Screena analyses this structured data to find any evidence of high-risk location.

Request Attributes

For more information about the bic attribute, refer to Matching Organizations.

Remember — Screena also detects 8 and 11-characters BIC codes in narrative.

Even if the BIC code is included into a long unstructured text, Screena will detect it effectively.

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/dataset-search"

Endpoint: POST rest/v2/dataset-search

Request: 8-character BIC code

{
    "queries": [{
        "sourceData": [{
            "bic": "BKMTIRTH"
        }],
        "targetData": [{
            "datasets": [{
                "label": "USA"
            }]
        }],
        "bicAlgo": {
            "type": "exact_match"
        }
    }]
}

Request: 11-character BIC code

{
    "queries": [{
        "sourceData": [{
            "bic": "BKMTIRTH056"
        }],
        "targetData": [{
            "datasets": [{
                "label": "USA"
            }]
        }],
        "bicAlgo": {
            "type": "exact_match"
        }
    }]
}

Request: 11-character BIC code in a narrative

{
    "queries": [{
        "sourceData": [{
            "narrative": "la banque utilisée est la BKMTIRTH056 qui s'occupe de gérer la transaction"
        }],
        "targetData": [{
            "datasets": [{
                "label": "USA"
            }]
        }]
    }]
}

Response Attributes

An array of matchingCountries is returned.

Attribute	What is returned ?
`country` String	Country matching with a high-risk location.
`ctrp` String	Cities, Towns, Regions & Ports matching with a high-risk location.
`risk` String	Risk related to the detected high-risk location.

Response

{
    "responseHeader": {
        "requestID": "GEN2054093905-1703152913898",
        "responded": "2023-12-21T10:01:53.898Z"
    },
    "results": [
        {
            "matchType": "st_match",
            "score": 1.00,
            "matchingNames": [
                {
                    "fullName": "BANK MELLAT",
                    "normalized": "bank mellat"
                }
            ],
            "sourceData": [
                {
                    "entityType": "organization",
                    "bic": "BKMTIRTH"
                }
            ],
            "targetData": [
                {
                    "dataID": "25019",
                    "entityType": "organization",
                    "names": [
                        {
                            "fullName": "BANK MELLAT",
                            "normalized": "bank mellat"
                        }
                    ],
                    "addresses": [
                        {
                            "street": "Head Office Bldg, 276 Taleghani Ave",
                            "city": "Tehran",
                            "country": "IR"
                        }
                    ],
                    "identityDocuments": [
                        {
                            "type": "Additional Sanctions Information -",
                            "number": "Subject to Secondary Sanctions"
                        }
                    ],
                    "contactInformation": [
                        {
                            "type": "Website",
                            "value": "www.bankmellat.ir"
                        }
                    ],
                    "additionalInformation": [
                        "All Branches Worldwide; (Linked To: MEHR EQTESAD BANK)"
                    ],
                    "categories": [
                        "SANCTION"
                    ],
                    "bic": "BKMTIRTH",
                    "active": true,
                    "keywords": [
                        "IFSR",
                        "SDGT",
                        "IRAN",
                        "Specially Designated Nationals (SDN) - Treasury Department"
                    ],
                    "sources": [
                        "Specially Designated Nationals (SDN) - Treasury Department",
                        "https://home.treasury.gov/policy-issues/financial-sanctions/specially-designated-nationals-and-blocked-persons-list-sdn-human-readable-lists",
                        "https://www.treasury.gov/resource-center/sanctions/SDN-List/Pages/default.aspx"
                    ],
                    "label": "USA",
                    "dataset": {
                        "label": "USA",
                        "category": "SANCTION",
                        "dateOfPublication": "2023-12-21T08:15:00.006",
                        "dateOfUpload": "2023-12-21T09:06:11.033"
                    },
                    "revision": 5704,
                    "created": "2023-02-08T07:28:21.558",
                    "updated": "2023-12-21T09:05:51.465",
                    "lastMatched": "2023-02-08T07:28:21.558",
                    "lastChecked": "2023-02-08T07:28:21.558"
                }
            ]
        },
        {
            "matchingCountries": [
                {
                    "country": "IR",
                    "risk": "Blacklisted Country (Iran)"
                }
            ],
            "sourceData": [
                {
                    "entityType": "organization",
                    "addresses": [
                        {
                            "country": "IR"
                        }
                    ],
                    "bic": "BKMTIRTH"
                }
            ]
        }
    ]
}

Named-Entities

About Objects

Screena is designed to match and search named-entities with an unprecedented level of precision.

A named-entity is a real-world object, such as individuals, locations, organizations, products, etc., that can be denoted with a proper name. It can be abstract or have a physical existence. Examples of named-entities include George Clooney, London, Ferrari F40, or anything else that can be named. Named-entities can simply be viewed as entity instances (e.g. London, United Kingdom is an instance of a location).

Entity Types

{
    "entityType": "individual"
}

The following table lists all of the possible values that can be used or returned for the entityType attribute. The model is currently being extended to other types of entities such as events, aircrafts and others.

Value	Description
individual	A human being, as opposed to an organization.
organization	Any organization that can be either private (i.e. business entity or non-governmental organization) or public (i.e. government, agencies ...).
vessel	All vehicles used in water, including ships, boats, hovercraft and submarines.
unknown	An entity type not within the range of the data inputter's knowledge.
location	A position on the world-map or marked by some distinguishing features. The level of granularity of location can vary depending on subcategories of the named-entity (place of birth, place of registry, address ...).
event Lab	Named events like social occasions, contests, wars, historical moments, ...
aircraft Lab	All vehicles that are able to fly by gaining support from the air, including Airplane, Rotorcraft, Lighter-Than-Air.

Some named-entities like dates (absolute or relative dates or periods) are not used independently from other objects, and this is why they are not included as an entityType value.

Technically, named-entity objects can be nested inside other objects. Each nested object must have a unique access path. The same field name can occur in nested objects in the same message. However, the full access name must still be unique.

Typically, addresses, placesOfBirth, and nationalities are named-entities belonging to the location type, and they also constitute attributes of an individual.

At this stage, locations in Screena are only matchable at the country-level granularity and only when nested under individual, organization, or vessel.

How it works — The entityType attribute has an impact on the matching process.

Associating a name with an entity type can reduce the number of unknown entityType and increase the accuracy of the matching.

Screena includes functions to identify the type of named-entity associated with a full name:

if entityType is specified, an AI model corresponding to the provided named-entity will be automatically selected, and will improve the results.
if entityType is not specified, Screena will attempt to determine it automatically.
if entityType is not specified and cannot be recognized, it will be set to "unknown" and a generic AI model will be used.

Dates

{
    "datesOfBirth": [{
        "date": "1922/1925"
    }, {
        "date": "1928"
    }]
}

A date attribute nested in an Object shall always be provided in accordance with the ISO 8601.
The date attribute is used for the following Objects:

datesOfRegistry
datesOfBirth
datesOfBuild
datesOfIssue
datesOfExpiry

Watch out — The next major version of our software (version 3.0) will support multiple values for all data fields, including datesOfIssue and datesOfExpiry. However, it is important to note that this version does not yet support arrays that can store multiple values for these fields. Currently, the software can only store a single value for each of these fields in the format of dateOfIssue, and dateOfExpiry. Please pay attention that the name of these attributes will differ from version 2 (singular form) to version 3 (plural form).

The following table lists all the possible ISO 8601-compatible formats that can be used in Screena for a date attribute.

Format	Description
YYYY-MM-DD	Year-Month-Day
YYYY	Year
YYYY/YYYY	Year Range

Sexes and Genders

{
    "sex": "F"
}

Sexual differentiation in human is crucial for identification of individuals.

Screena is capable of identifying the gender of an individual based on the fullName or givenName attribute and return gender data into the sex attribute. If the sex cannot be recognized, it will be set to "unknown".

The following table lists all of the possible values that can be used for the sex attribute.

Value	Description
f or F	female
m or M	male
i or I Lab	intersex
u or U	unknown

Countries

{
    "nationalities": [{
        "country": "US"
    }, {
        "country": "GR"
    }]
}

The following table lists all of the possible child attributes for:

nationalities
flags

Attribute	Description	Required
`country` String	Country in ISO 3166-alpha 2 format.	No

Places

{
    "placesOfBirth": [{
        "city": "New York City",
        "state": "New York",
        "country": "US"
    }]
}

The following table lists all of the possible child attributes for:

placesOfBirth
placesOfBuild
placesOfRegistry
placesOfIssue

Watch out — The next version of our software (version 3.0) will support multiple values for all data fields, including placesOfRegistry and placesOfIssue. However, it is important to note that this version does not yet support arrays that can store multiple values for these fields. Currently, the software can only store a single value for each of these fields in the format of placeOfRegistry and placeOfIssue. Please pay attention that the name of these attributes will differ from version 2 (singular form) to version 3 (plural form).

Attribute	Description	Required
`city` String	Any human settlement such as a metropolis, city, town or village.	No
`state` String	First-level administrative division.	No
`country` String	Country in ISO 3166-alpha 2 format.	No

Addresses

{
    "addresses": [{
            "street": "trente-six avenue Georges Mandel",
            "city": "Paris",
            "country": "FR"
        },
        {
            "streetNumber ": "7",
            "streetName": "Via Caio Valerio Catullo",
            "zipCode": "25019",
            "city": "Sirmione",
            "country": "IT"
        }
    ]
}

The following table lists all of the possible child attributes for addresses.

Attribute	Description	Required
`fullAddress` String	Full address in unstructured format.	No
`streetNumber` String	Unique number to each building in a street or area, which makes it easier to locate a particular building or vacant lot.	No
`streetName` String	The name of a street. Street is used as a generic attribute, which can be anything that connects two points on a map: Street, Road, Way, Avenue, Boulevard, Lane, Drive, ...	No
`street` String	The name of a street, including the street name and the street number (in case no separation can be made between street address number and street name).	No
`poBox` String	A box with a number in a post office to which letters and parcels can be sent and from which you they can be collected.	No
`zipCode` String	Postal code used for mail sorting.	No
`city` String	Any human settlement such as a metropolis, city, town or village.	No
`state` String	First-level administrative division.	No
`country` String	Country in ISO 3166-alpha 2 format.	No

Identity Documents

{
    "identityDocuments": [{
        "type": "Passport",
        "country": "FR",
        "description": "French ID number seems erroneous",
        "number": "86YH34567",
        "placeOfIssue": {
            "city": "Amsterdam",
            "country": "NL"
        },
        "dateOfIssue": {
            "date": "2020-12-15"
        },
        "dateOfExpiry": {
            "date": "2030-12-15"
        }
    }]
}

The following table lists all of the possible child attributes for identityDocuments.

Attribute	Description	Required
`number` String	Unique number of the Identity Document.	No
`type` String	The type of Identity Document (e.g. Passport, ID card, Social Security card, Driver's license, Birth certificate, Death certificate, Other identity documents,...)	No
`country` String	The country which has issued the Identity Document in ISO 3166-alpha 2 format.	No
`dateOfIssue` String	The date on which a government body issued the Identity Document. Refer to Dates for more info.	No
`placeOfIssue` String	The place (City and Country) where the government body issued the Identity Document. See child attributes for Places.	No
`dateOfExpiry` String	The date on which the Identity Document expires. Refer to Dates for more info.	No
`description` String	Statement giving characteristics of the Identity Document.	No

Contact Information

{
    "contactInformation": [{
            "type": "Phone",
            "value": "+963 - 11- 2260805"
        },
        {
            "type": "Internet Site",
            "value": "https://www.champress.net"
        },
        {
            "type": "Email",
            "value": "mail@champress.com"
        }
    ]
}

The following table lists all of the possible child attributes for contactInformation.

Attribute	Description	Required
`type` String	The type of Contact Information.	No
`value` String	The value of the attribute.	No

Digital Currencies

{
    "digitalCurrencies": [{
            "currency": "XMR",
            "identifier": "5be5543ff73456ab9f2d207887e2af87322c651ea1a873c5b25b7ffae456c320"
        },
        {
            "currency": "ETC",
            "identifier": "0xd882cfc20f52f2599d84b8e8d58c7fb62cfe344b"
        },
        {
            "currency": "ZEC",
            "identifier": "t1g7wowvQ8gn2v8jrU1biyJ26sieNqNsBJy"
        },
        {
            "currency": "DASH",
            "identifier": "XnPFsRWTaSgiVauosEwQ6dEitGYXgwznz2"
        },
        {
            "currency": "BTG",
            "identifier": "GPwg61XoHqQPNmAucFACuQ5H9sGCDv9TpS"
        },
        {
            "currency": "XBT",
            "identifier": "1Q6saNmqKkyFB9mFR68Ck8F7Dp7dTopF2W"
        },
        {
            "currency": "XBT",
            "identifier": "1DDA93oZPn7wte2eR1ABwcFoxUFxkKMwCf"
        },
        {
            "currency": "ETH",
            "identifier": "0xd882cfc20f52f2599d84b8e8d58c7fb62cfe344b"
        },
        {
            "currency": "LTC",
            "identifier": "LNwgtMxcKUQ51dw7bQL1yPQjBVZh6QEqsd"
        }
    ]
}

The following table lists all of the possible child attributes for digitalCurrencies.

Attribute	Description	Required
`currency` String	The type of Digital Currency, preferably its symbol.	No
`identifier` String	The identifier of the Digital Currency.	No

Algorithms

Parametrization

{
    "type": "exact_match",
    "nullMatch": true,
    "exclude": [
        "vessel"
    ]
}

The following table lists the attributes that can be used to parametrize binary-matching, date-matching, and country-matching algorithms in Screena.

Attribute	Description	Required
`type` String	Type of the matching Algorithm. See below for more info.	Yes
`nullMatch` Boolean	Parameter to specify how a match should be handled when one attribute associated with the algorithm is either empty or not provided: if `nullMatch` is true, the attribute will be deemed matching; if `nullMatch` is false, the attribute will be deemed not matching; if `nullMatch` is not provided, Screena will set the parameter at true.	No
`include`(New) Array of Strings	This attribute is currently only usable for `entityTypeAlgo`, `categoryAlgo` and `keywordAlgo`. It can be used to narrow matches to specific entity types, data record categories or data record keywords.	No
`exclude`(New) Array of Strings	This attribute is currently only usable for `entityTypeAlgo`, `categoryAlgo` and `keywordAlgo`. It can be used to exclude matches for specific entity types, data record categories or data record keywords. It is especially helpful to prevent irrelevant matches such as those of individuals or organizations with vessels.	No

Normalization

Request (Normalisation)

{
    "queries": [{
        "sourceData": [{
            "names": [{
                "fullName": "Reginald Williams"
            }],
            "addresses": [{
                "fullAddress": "SOPTCHOM TEMDEMNO, YAOUNDE"
            }]
        }],
        "targetData": [{
            "datasets": [{
                "label": "INTERPOL"
            }]
        }],
        "addressAlgo": {
            "type": "same_region",
            "nullMatch": true
        }
    }]
}

Response (Normalisation)

{
    "responseHeader": {
        "requestID": "GEN2054093905-1642774501044",
        "responded": "2022-01-21T14:15:01.044Z"
    },
    "results": [{
        "matchType": "no_match",
        "sourceData": [{
            "entityType": "unknown",
            "names": [{
                "fullName": "Reginald Williams",
                "normalized": "reginald williams"
            }],
            "addresses": [{
                "country": "CM",
                "fullAddress": "SOPTCHOM TEMDEMNO, YAOUNDE"
            }]
        }]
    }]
}

The normalization process harmonizes and transforms data into a format that makes attribute matching consistent.

Normalization is specific to each Object, and influences the results provided in the normalized attribute of a response:

Date Normalization
Country Normalization
Name Normalization

Binary-Matching Algorithms

{
    "entityTypeAlgo": {
        "type": "exact_match",
        "nullMatch": true,
        "exclude": [
            "vessel", "organization"
        ]
    }
}

This chapter describes the algorithms that can be used for the following attributes:

entityTypeAlgo
sexAlgo
categoryAlgo
keywordAlgo

How it works — entityTypeAlgo is used to reject matches between entities with different entityType (e.g. individual vs organization).

In some cases, it is not possible to determine the entityType (e.g. SWIFT messages) and it is then advisable to set entityType with the value "unknown", which will make possible to get matches independently from the entityType.

However, the matches obtained in this context may not be always relevant. That's why before applying the default model for "individuals", in case no entityType is provided, Screena attempts to select the model corresponding to the entityType of the candidate matches found in the targetData.

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/dataset-search-engine"

Request: The following example shows how to search for a name on the USA list limited to the "Sectoral Sanctions Identifications List (SSI)" sanctions program using the algorithm keywordAlgo.

{
    "queries": [{
        "sourceData": [{
            "names": [{
                "fullName": "Hector Villareal"
            }]
        }],
        "targetData": [{
            "datasets": [{
                "label": "USA"
            }]
        }],
        "threshold": 0.8,
        "keywordAlgo": {
            "type": "ignore",
            "include": [
                "Sectoral Sanctions Identifications List (SSI)"
            ]
        }
    }]
}

Algorithm Types

Value	Description
exact_match Default	Exactly match the attribute.
ignore	The attribute is ignored for the match. If a field is empty or set with unknown value, the application will operate as in the presence of the "ignore" algorithm.

Identifier-Matching Algorithms

{
    "identityDocumentAlgo": {
        "type": "contains",
        "nullMatch": true
    }
}

This chapter describes the algorithms that can be used for the following attributes:

identityDocumentAlgo
bicAlgo
leiAlgo
digitalCurrencyAlgo

Algorithm Types

Value	Description
exact_match Default	Exactly match the attribute.
starts_with	Search for a query string at the beginning of a text string. It returns a match if all the characters in the query string appear in the same order at the beginning of the text string.
ends_with	Search for a query string at the end of a text string. It returns a match if all the characters in the query string appear in the same order at the end of the text string.
contains	Search for a query string within a text string. It returns a match if all the characters in the query string appear in the text string in the same order, regardless of additional characters in between.
pattern	Identify strings of characters that match a specific pattern, while ignoring those that do not. It matches the input string with a pattern that includes an obscured version of the string, with only certain characters visible. For example, the string "458.211.389-12" will match with "*.211.389-" but will not match with "*.058.029-".
ignore	The attribute is ignored for the match. If a field is empty or set with unknown value, the application will operate as in the presence of the "ignore" algorithm.

Date-Matching Algorithms

{
    "dateOfBirthAlgo": {
        "type": "same_year",
        "nullMatch": true
    }
}

This chapter describes the algorithms that can be used for the following attributes:

dateOfBirthAlgo
dateOfRegistryAlgo
dateOfBuildAlgo

Algorithm Types

Value	Description
same_day_month_year	Match dates within the same Day/Month/Year.
same_month_year	Match dates within the same Month/Year.
same_year	Match dates within the same Year.
same_quadrennium	Match dates within the same Quadrennium (source date +/-2 year).
same_decade	Match dates within the same Decade (source date +/-5 year).
ignore Default	The attribute is ignored for the match. If a field is empty, the application will operate as in the presence of the "ignore" algorithm.

Normalization

{
    "date": "1985-10-14",
    "normalized": "1985"
}

The choice of the algorithm type in the request influences the date formats in the normalized attribute of the response. The normalized attribute format is displayed according to both:

the date formats used in the request, as provided in sourceData and targetData.
the choice of the Date-Matching algorithm.

Algorithm Type vs Date Format	YYYY-MM-DD	YYYY-MM	YYYY	YYYY/YYYY
same_day_month_year	YYYY-MM-DD	YYYY-MM-01 /YYYY-MM-31	YYYY-01-01 /YYYY-12-31	YYYY-01-01 /YYYY-12-31
same_month_year	YYYY-MM	YYYY-MM	YYYY-01 /YYYY-12	YYYY-01 /YYYY-12
same_year	YYYY	YYYY	YYYY	YYYY/YYYY
same_quadrennium	YYYY-MM-DD /YYYY-MM-DD calculate quadrennium	YYYYY-01-01 /YYYY-12-31 calculate quadrennium	YYYY-01-01 /YYYY-12-31 calculate quadrennium	YYYY-01-01 /YYYY-12-31 calculate quadrennium
same_decade	YYYY-MM-DD /YYYY-MM-DD calculate decade	YYYY-01-01 /YYYY-12-31 calculate decade	YYYY-01-01 /YYYY-12-31 calculate decade	YYYY-01-01 /YYYY-12-31 calculate decade
ignore	no display	no display	no display	no display

Country-Matching Algorithms

{
    "nationalityAlgo": {
        "type": "same_region",
        "nullMatch": true
    }
}

This chapter describes the algorithms that can be used for the following attributes:

placeOfBirthAlgo
placeOfRegistryAlgo
addressAlgo
nationalityAlgo
flagAlgo

Algorithm Types

Value	Description
same_country	Match when countries are the same.
same_subregion	Match countries when they are in the same subregion based on the United Nations geoscheme.
same_region	Match countries when they are in the same region based on the United Nations geoscheme.
ignore Default	The attribute is ignored for the match. If a field is empty, the application will operate as in the presence of the "ignore" algorithm.

Normalization

{
    "country": "DE",
    "normalized": "EUROPE"
}

The choice of the algorithm type in the request influences the information provided in the normalized attribute of the response.

Value	Normalization
same_country	Display the matching country in ISO 3166-alpha 2 format.
same_subregion	Display the matching subregion based on the United Nations geoscheme.
same_region	Display the matching region based on the United Nations geoscheme.
ignore	The attribute is not displayed in `normalized`. If a field is empty, the application will operate as in the presence of the "ignore" algorithm.

United Nations Geoscheme

The following table lists all of the regions, subregions, and countries according to the United Nations geoscheme grouping.

Regions	Subregions	Countries
Africa	Northern Africa	Algeria, Egypt, Western Sahara, Libya, Morocco, Sudan, Tunisia
Africa	Eastern Africa	Burundi, Djibouti, Eritrea, Ethiopia, Kenya, Comoros, Madagascar, Mauritius, Malawi, Mozambique, Réunion, Rwanda, Seychelles, Somalia, South Sudan, Tanzania, Uganda, Mayotte, Zambia, Zimbabwe
Africa	Middle Africa	Angola, Congo, Democratic Republic of the, Central African Republic, Congo, Republic of the, Cameroon, Gabon, Guinea, Sao Tome and Principe, Chad
Africa	Southern Africa	Botswana, Lesotho, Namibia, Eswatini, South Africa
Africa	Western Africa	Burkina Faso, Benin, Cote d'Ivoire, Cabo Verde, Ghana, The Gambia, Equatorial Guinea, Guinea-Bissau, Liberia, Mali, Mauritania, Niger, Nigeria, Saint Helena, Ascension & Tristan da Cunha, Sierra Leone, Senegal, Togo
Americas	Caribbean	Antigua and Barbuda, Netherlands Antilles, Anguilla, Aruba, Saint-Barthélemy, Bonaire, Sint Eustatius & Saba, The Bahamas, Cuba, Curaçao, Dominica, Dominican Republic, Grenada, Guadeloupe, Haiti, Jamaica, Saint Kitts and Nevis, Cayman Islands, Saint Lucia, Saint-Martin (French part), Martinique, Montserrat, Puerto Rico, Sint Maarten (Dutch part), Turks & Caicos Islands, Trinidad and Tobago, Saint Vincent and the Grenadines, Virgin Islands (British), Virgin Islands (US)
Americas	Southern America	Argentina, Barbados, Bolivia, Brazil, Chile, Colombia, Ecuador, Falkland Islands (Malvinas), French Guiana, South Georgia & South Sandwich Islands, Guyana, Peru, Paraguay, Suriname, Uruguay, Venezuela
Americas	Northern America	Bermuda, Canada, Greenland, Saint Pierre & Miquelon, United States of America
Americas	Central America	Belize, Costa Rica, Guatemala, Honduras, Mexico, Nicaragua, Panama, El Salvador
Europe	Southern Europe	Spain, Greece, Italy, Malta, Portugal, Slovenia, Kosovo, Andorra, Albania, Bosnia and Herzegovina, Gibraltar, Croatia, Montenegro, North Macedonia, Serbia, San Marino, Holy See (Vatican City)
Europe	Northern Europe	Aland Islands, Denmark, Estonia, Finland, Faroe Islands, United Kingdom, Guernsey, Ireland, Isle of Man, Iceland, Jersey, Lithuania, Latvia, Norway, Sweden, Svalbard & Jan Mayen Islands
Europe	European Union	Austria, Belgium, Bulgaria, Cyprus, Czechia, Germany, Denmark, Estonia, Spain, European Union, Finland, France, Greece, Hungary, Italy, Lithuania, Luxembourg, Latvia, Malta, Netherlands, Norway, Poland, Portugal, Romania, Sweden, Slovenia, Slovakia
Europe	Western Europe	Austria, Belgium, Switzerland, Germany, France, Liechtenstein, Luxembourg, Monaco, Netherlands
Europe	Eastern Europe	Bulgaria, Belarus, Czechia, Hungary, Moldova, Poland, Romania, Russia, Slovakia, Ukraine
Asia	Western Asia	Gaza Strip, United Arab Emirates, Armenia, Azerbaijan, Bahrain, Georgia, Israel, Iraq, Jordan, Kuwait, Lebanon, Oman, Palestinian Territory, Qatar, Saudi Arabia, Syria, Turkey, Yemen, Cyprus
Asia	Eastern Asia	Burundi, Djibouti, Eritrea, Ethiopia, Kenya, Comoros, Madagascar, Mauritius, Malawi, Mozambique, Réunion, Rwanda, Seychelles, Somalia, South Sudan, Tanzania, Uganda, Mayotte, Zambia, Zimbabwe
Asia	Central Asia	Kyrgyzstan, Kazakhstan, Tajikistan, Turkmenistan, Uzbekistan
Asia	South-Eastern Asia	Brunei, Indonesia, Cambodia, Laos, Burma, Malaysia, Philippines, Singapore, Thailand, Timor-Leste, Vietnam
Asia	Southern Asia	British Indian Ocean Territory, Afghanistan, Bangladesh, Bhutan, India, Iran, Sri Lanka, Maldives, Nepal, Pakistan
Oceania	Polynesia	American Samoa, Cook Islands, Niue, French Polynesia, Pitcairn, Tokelau, Tonga, Tuvalu, Wallis & Futuna Islands, Samoa
Oceania	Micronesia	United States Minor Outlying Islands, Micronesia, Federated States of, Guam, Kiribati, Marshall Islands, Northern Mariana Islands, Nauru, Palau
Oceania	Melanesia	Fiji, New Caledonia, Papua New Guinea, Solomon Islands, Vanuatu
Oceania	Australia & New Zealand	Australia, Cocos (Keeling) Islands, Christmas Island, Heard Island & Mcdonald Islands, Norfolk Island, New Zealand
Antarctica	Antarctica	Antarctica, Bouvet Island, French Southern Territories

Name-Matching Algorithms

Screena offers a set of technologies to address the specific needs and demands of managing, searching, scoring, and matching multicultural name Datasets.

Normalization

{
    "surname": "MANSUR",
    "givenName": "'Abd el-Ḥamīd",
    "normalized": "abd el hamid mansur"
}

Before processing names, Screena automatically generates normalized versions of name tokens.

Normalization ensures consistency in how your name data is matched by:

Switching all characters to lower case
Removing all diacritics (e.g.: accents)
Removing punctuation within words (e.g.: apostrophes)
Managing punctuation between words
Using transliteration mechanisms (when required). Screena will always return a romanized name.
Removing prefixes and suffixes (e.g.: Jr., Sr., Mr., PLC, www,...)
Harmonizing numbers in digits and letters (e.g.: 3 = three, 3rd = third, ...)

Algorithm Types

Instead of just searching or matching names using standard methods, Screena uses sophisticated AI to provide the best possible real-time results.

Screena does not establish a phonetic or edit distance similarity between 2 strings, but the probability that they are the same name or named-entity.

The following table gives some examples which allow to understand the important advantage that this brings compared to standard solutions and algorithms.

String 1	String 2	Screena Probability	Levenshtein Distance	Jaro Distance	Metaphone Phonetic
b r u c e m a l m u t h	bruce malmuth	98%	57%	0%	71%
al-qaida in the arabian peninsula/ansar al-sharia	//al-qa'ida in the arabian peninsula	89%	61%	86%	70%
Mrs Maddie Ziegler	Madison Ziegler	100%	56%	73%	67%

Screena also automatically adapts to Name Cultures specifics.

Threshold

You can use the threshold attribute to adjudicate the relative yield of true-positive versus true-negative cases. By default, it is set at 60% which provides maximum recall as requested by the majority of users.

Raising the threshold would result in fewer matches, which would increase the possibility of false-negatives and vice-versa.

A score below the threshold value provided in the request is rejected. Then a match processed by the AI engine can end up as either discarded or acknowledged.

Name-match Types

{
    "matchType": "ai_accept",
    "score": 0.98
}

The following table lists all of the possible values that can be returned for the matchType attribute.

Value	Description
ai_reject	Discarded by AI (below threshold): A match score based on probabilistic calculation is returned. Every score below the above-mentioned threshold is considered as rejected.
ai_accept	Acknowledged by AI (above threshold): A match score based on probabilistic calculation is returned. Every score above the above-mentioned threshold is considered as accepted.
no_match	No Match: The probability that the 2 strings are the same is so low that it is not considered.
st_match	Straightforward Match: A match score is returned. Such cases use deterministic rules. AI would have a counterproductive effect in terms of performance and quality - So, they are not processed through it. Every score above the above-mentioned threshold is considered as accepted.

Name Beginning & End

{
    "nameAlgo": [{
        "endBeginBoost": true,
        "entityTypes": ["individual", "vessel"],
        "minNbrOfToken": 4

    }, {
        "endBeginBoost": false,
        "entityTypes": ["organization", "unknown"],
        "minNbrOfToken": 4
    }]
}

Similarities in the beginning and end of names can be more significant than other name parts.

You can decide to apply a boost if the beginning and the end of two names are similar.

In Arabic, Aysha Mazar Rashed Mohamed Erakat is typically the daughter of Mazar Rashed Mohamed Erakat:

If the endBeginBoost attribute is set to "false" there is no influence on the score.
If the endBeginBoost attribute is set to "true" the score is reduced to 0%.

Conversely, in Spanish Pablo Diego José Francisco de Paula Juan Nepomuceno María de los Remedios Cipriano de la Santísima Trinidad Ruiz y Picasso is Pablo Picasso:

If the endBeginBoost attribute is set to "false" there is no influence on the score.
If the endBeginBoost attribute is set to "true" the score is increased to 100%.

Depending on the circumstances of your data you can adapt the endBeginBoost value.

The following table lists the attributes used to boost the score when beginning and end of name pairs is similar.

Attribute	Description	Required
`endBeginBoost` Boolean	Parameter to specify if a boost is applied if the beginning and end of the names pair is dissimilar/similar if `endBeginBoost` is true, the score boost is applied; if `endBeginBoost` is false, the score boost is not applied; if `endBeginBoost` is not provided, Screena will set the parameter at false.	No
`entityTypes` Array of Strings	Types of named-entity to which the boost applies. Refer to Named-Entities Objects for more info. If not provided, it applies to all named-entities by default	No
`minNbrOfToken` String	This is the minimum number of name elements (token) per string.	No

Remember — The minNbrOfToken attribute is typically used to avoid that short names (i.e., those with a low number of tokens) generate an inordinate number of matches.

Transliteration

Request: The API can be queried directly with names in original scripts using the transliteration capability of Screena.

{
    "queries": [{
        "sourceData": [{
            "names": [{
                "fullName": "毛泽东"
            }]
        }],
        "targetData": [{
            "names": [{
                "fullName": "Máo Zédōng"
            }]
        }]
    }]
}

Response

{
    "results": [{
        "matchType": "st_match",
        "score": 0.98,
        "sourceData": [{
            "entityType": "unknown",
            "names": [{
                "fullName": "毛泽东",
                "normalized": "mao ze dong"
            }],
            "cultureCodes": [
                "zh"
            ]
        }],
        "targetData": [{
            "entityType": "unknown",
            "names": [{
                "fullName": "Máo Zédōng",
                "normalized": "mao zedong"
            }],
            "cultureCodes": [
                "zh"
            ]
        }]
    }]
}

Screena matches name variants across languages and writing systems.

Romanization mechanisms convert names from one script to Roman script automatically and vice-versa.

Script	Transliteration	Method
Latin	N/A	N/A
Arabic	-	-
Chinese	Romanized Chinese	Hanyu Pinyin romanization
Cyrillic	Romanized Cyrillic	International Civil Aviation Organization romanization as published published in Doc 9303 "Machine Readable Travel Documents, Part 3"
Greek	Romanized Greek	ISO843_1997 romanization
Armenian Lab	-	-
Bengali Lab	-	-
Bharat Lab	-	-
Devanagari Lab	-	-
Ge'ez Lab	-	-
Georgian Lab	-	-
Hangeul Lab	-	-
Hebrew Lab	-	-
Japanese Lab	-	-
Khmer Lab	-	-
Lao Lab	-	-
Mongolian Lab	-	-
Tengwar Lab	-	-
Thai Lab	-	-
Tifinagh Lab	-	-

Name Cultures

{
    "normalized": "xi jinping",
    "cultureCodes": [
        "zh"
    ]
}

As names differ from one part of the world and from one cultural group to another, Screena automates the identification of individual name cultures in romanized scripts.

If successfully detected, each culture is assigned a two-letter code based on the ISO 639-1. Identifying the culture of a name significantly improves the quality of name matching.

This knowledge allows the correct set of AI models based on the culture to be applied to the name.

The following table lists all of the possible values that can be returned for the cultureCodes attribute based on the ISO 639-1.

Value	Description
xx	Ambiguous: no valid culture can be determined
af	Afrikaans
ak	Akan
sq	Albanian
am	Amharic
ar	Arabic
an	Aragonese
hy	Armenian
as	Assamese
az	Azerbaijani
eu	Basque
be	Belarusian
bn	Bengali
bs	Bosnian
br	Breton
bg	Bulgarian
my	Burmese
ca	Catalan, Valencian
ce	Chechen
ny	Chichewa, Chewa, Nyanja
zh	Chinese
kw	Cornish
co	Corsican
hr	Croatian
cs	Czech
da	Danish
nl	Dutch, Flemish
en	English
et	Estonian
ee	Ewe
fi	Finnish
fr	French
ff	Fulah
gl	Galician
ka	Georgian
de	German
el	Greek, Modern (1453–)
gu	Gujarati
ha	Hausa
he	Hebrew
hz	Herero
hi	Hindi
ho	Hiri Motu
hu	Hungarian
id	Indonesian
ga	Irish
ig	Igbo
io	Ido
is	Icelandic
it	Italian
iu	Inuktitut
ja	Japanese
kn	Kannada
kk	Kazakh
km	Central Khmer
ki	Kikuyu, Gikuyu
ky	Kirghiz, Kyrgyz
kg	Kongo
ko	Korean
ku	Kurdish
kj	Kuanyama, Kwanyama
lg	Ganda
li	Limburgan, Limburger, Limburgish
lt	Lithuanian
lo	Lao
lu	Luba-Katanga
lv	Latvian
gv	Manx
mk	Macedonian
ms	Malay
ml	Malayalam
mr	Marathi
mn	Mongolian
nv	Navajo, Navaho
nd	North Ndebele
ne	Nepali
ng	Ndonga
no	Norwegian
nr	South Ndebele
oc	Occitan
oj	Ojibwa
om	Oromo
or	Oriya
pa	Punjabi, Panjabi
fa	Persian
pl	Polish
ps	Pashto, Pushto
pt	Portuguese
ro	Romanian, Moldavian, Moldovan
ru	Russian
sa	Sanskrit
sc	Sardinian
sr	Serbian
gd	Gaelic, Scottish Gaelic
sn	Shona
sk	Slovak
sl	Slovenian
so	Somali
st	Southern Sotho
es	Spanish, Castilian
sw	Swahili
ss	Swati
sv	Swedish
ta	Tamil
te	Telugu
tg	Tajik
th	Thai
bo	Tibetan
tk	Turkmen
tl	Tagalog
tn	Tswana
tr	Turkish
tt	Tatar
ug	Uighur, Uyghur
uk	Ukrainian
ur	Urdu
uz	Uzbek
vi	Vietnamese
cy	Welsh
fy	Western Frisian
xh	Xhosa
yi	Yiddish
yo	Yoruba
zu	Zulu
ab	Abkhazian Lab
aa	Afar Lab
av	Avaric Lab
ae	Avestan Lab
ay	Aymara Lab
bm	Bambara Lab
ba	Bashkir Lab
bh	Bihari languages Lab
bi	Bislama Lab
ch	Chamorro Lab
cv	Chuvash Lab
cr	Cree Lab
dv	Divehi, Dhivehi, Maldivian Lab
dz	Dzongkha Lab
fo	Faroese Lab
fj	Fijian Lab
gn	Guarani Lab
ht	Haitian, Haitian Creole Lab
ik	Inupiaq Lab
jv	Javanese Lab
kl	Kalaallisut, Greenlandic Lab
kr	Kanuri Lab
ks	Kashmiri Lab
rw	Kinyarwanda Lab
kv	Komi Lab
la	Latin Discarded
lb	Luxembourgish, Letzeburgesch Lab
ln	Lingala Lab
mg	Malagasy Lab
mt	Maltese Lab
mi	Maori Lab
mh	Marshallese Lab
na	Nauru Lab
nb	Norwegian Bokmål Lab
nn	Norwegian Nynorsk Lab
ii	Sichuan Yi, Nuosu Lab
os	Ossetian, Ossetic Lab
pi	Pali Lab
qu	Quechua Lab
rm	Romansh Lab
rn	Rundi Lab
sd	Sindhi Lab
se	Northern Sami Lab
sm	Samoan Lab
sg	Sango Lab
si	Sinhala, Sinhalese Lab
su	Sundanese Lab
ti	Tigrinya Lab
to	Tonga (Tonga Islands) Lab
ts	Tsonga Lab
tw	Twi Lab
ty	Tahitian Lab
ve	Venda Lab
vo	Volapük Lab
wa	Walloon Lab
wo	Wolof Lab
za	Zhuang, Chuang Lab
eo	Esperanto Discarded
ia	Interlingua (International Auxiliary Language Association) Discarded
ie	Interlingue, Occidental Discarded
cu	Church Slavic, Old Slavonic, Church Slavonic, Old Bulgarian, Old Church Slavonic Discarded

Libraries

About

Screena Firm is designed for users that want to build their own libraries of Stopwords, Synonyms, Prefixes and Suffixes. You can provide your own Libraries to either replace or supplement the default ones.

Libraries are paramount to keep false negatives rates as low as possible, as they are used in the Name Normalization process and ensure consistency in how your data is matched. For example, Synonyms will help to determine which names should be considered equal despite being syntactically dissimilar.

Libraries can be managed independently. There is no need to populate all of the Libraries in one go (i.e., Prefixes, Suffixes, Synonyms, and Stopwords) through a single API call. For example, it is quite possible to populate Prefixes all while leaving Suffixes unchanged when calling the method to populate Libraries.

The following Libraries are supported:

Library	Description
Prefixes	A Prefix is placed "before" a name and is not part of it: Titles: "Mr.", "MM.", "Dr.", etc Academic qualifications: "M.D.", "CPA", etc Organization designators: "The Bank", "La Banque", etc
Suffixes	A Suffix is placed "after" a name and is not part of it: Qualifiers: "Jr", "Esq", etc Organization designators: "Inc.", "LLC", "Limited Liability Corporation", etc
Stopwords	A Stopword is a word that adds no meaning to name and therefore is not included in the matching: For example, a search for "ARMCHAIRS OF NEBRASKA INC." shall match with "ARMCHAIRS NEBRASKA INC." because the preposition "OF" shall not affect the calculation.
Synonyms	All words to define names like alternative spellings, nicknames, diminutives,... : For example, "20th" and "Twentieth", "Bill" and "William", "Ronald" and "Ron", etc.
Locations	All locations and their associated level of risk : For example, "Syria" with "Blacklisted Country", "Syria" with "Blacklisted Region", etc.

Watch out — It is important not to inconsiderately change the data present in the libraries because they have a significant impact on the functioning of the application:

Do not create duplicate entries in a Library. The combination of value and entityTypes values shall be unique across the whole set of prefixes and suffixes. Otherwise, Screena will generate an error message.
Be aware that certain suffixes, stopwords or prefixes can also be an important component of a name.
Uppercase and lowercase letters are not treated as distinct (case-insensitive). Do not create separate Library entries.
The current release of Screena includes only "OF" and "THE" as stopwords, and there is a good reason for it. You should be very careful if you decide to add more.
It is not possible to update a record into a Library in isolation (record-by-record updates are not authorized).
You shall always maintain the full content of a Library and populate the latter with this set of information.
When a populating method of a Library is called, Screena will first erase the entire library, then populate it with the entries posted in the request.

Populating Prefixes Library

This POST method allows to populate the Prefixes Library in a single API call.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/libraries/populate"

Endpoint: POST rest/v2/libraries/populate

Request

{
    "libraries": [{
        "prefixes": [{
                "value": "Mr.",
                "entityTypes": ["individual", "unknown"],
                "sex": "M",
                "active": true
            },
            {
                "value": "MM.",
                "entityTypes": ["individual", "unknown"],
                "sex": "M",
                "active": true
            }
        ]
    }]
}

Attribute	Description	Required
`prefixes` Array of Prefix Objects	Set of Prefixes used to populate the Library.	Yes
`value` String	Value of the Prefix.	Yes
`entityTypes` Array of Strings	Types of named-entity to which the value applies. Refer to Named-Entities Objects for more info.	Yes
`sex` String	Sex related to the Prefix. Only applicable to an individual.	No
`active` Boolean	If `active` is true, the record is active and will be used for normalization and gender detection. If `active` is false, the record is not active and won't be used for normalization and gender detection. If `active` is not provided, Screena will set the parameter at true.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true,
    "processed": "2"
}

Returns a confirmation that the prefixes were successfully populated.

Attribute	Description
`success` Boolean	If `success` is true, the Library is successfully populated. Otherwise an error is returned.
`processed` Integer	Count of the total number of Records with which the Library has been populated.

Populating Suffixes Library

This POST method allows to populate the Suffixes Library in a single API call.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/libraries/populate"

Endpoint: POST rest/v2/libraries/populate

Request

{
    "libraries": [{
        "suffixes": [{
                "value": "LLC",
                "entityTypes": ["organization"],
                "active": true
            },
            {
                "value": "Jr",
                "entityTypes": ["individual"],
                "sex": "M",
                "active": true
            }
        ]
    }]
}

Attribute	Description	Required
`suffixes` Array of Suffix Objects	Set of Suffixes used to populate the Library.	Yes
`value` String	Value of the Suffix.	Yes
`entityTypes` Array of Strings	Type of named-entity to which the value applies. Refer to Named-Entities Objects for more info.	Yes
`sex` String	Sex related to the Suffix. Only applicable to an individual.	No
`active` Boolean	If `active` is true, the record is active and will be used for normalization and gender detection. If `active` is false, the record is not active and won't be used for normalization and gender detection. If `active` is not provided, Screena will set the parameter at true.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true,
    "processed": "2"
}

Returns a confirmation that the suffixes were successfully populated.

Attribute	Description
`success` Boolean	If `success` is true, the Library is successfully populated. Otherwise an error is returned.
`processed` Integer	Count of the total number of Records with which the Library has been populated.

Populating Stopwords Library

This POST method allows to populate the Stopwords Library in a single API call.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/libraries/populate"

Endpoint: POST rest/v2/libraries/populate

Request

{
    "libraries": [{
        "stopwords": [{
            "value": "of",
            "active": true
        }]
    }]
}

Attribute	Description	Required
`stopwords` Array of Stopword Objects	Set of Stopwords used to populate the Library.	Yes
`value` String	Value of the Stopword.	Yes
`active` Boolean	If `active` is true, the record is active and will be used for normalization. If `active` is false, the record is not active and won't be used for normalization. If `active` is not provided, Screena will set the parameter at true.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true,
    "processed": "1"
}

Returns a confirmation that the stopwords were successfully populated.

Attribute	Description
`success` Boolean	If `success` is true, the Library is successfully populated. Otherwise an error is returned.
`processed` Integer	Count of the total number of Records with which the Library has been populated.

Populating Synonyms Library

This POST method allows to populate the Synonyms Library in a single API call.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/libraries/populate"

Endpoint: POST rest/v2/libraries/populate

Request

{
    "libraries": [{
        "synonyms": [{
            "entityTypes": ["individual", "unknown"],
            "value": "Arnold",
            "sex": "M",
            "altValues": ["Arnie"],
            "active": true
        }]
    }]
}

Attribute	Description	Required
`synonyms` Array of Synonym Objects	Set of Synonyms used to populate the Library.	Yes
`value` String	Value of the Synonym.	Yes
`altValues` Array of Strings	Alternative values for a Synonym. Only applicable to Synonyms.	Yes
`entityTypes` Array of Strings	Types of named-entity to which the value applies. Refer to Named-Entities Objects for more info.	Yes
`sex` String	Sex related to the Synonym. Only applicable to an individual.	No
`active` Boolean	If `active` is true, the record is active and will be used for normalization and gender detection. If `active` is false, the record is not active and won't be used for normalization and gender detection. If `active` is not provided, Screena will set the parameter at true.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true,
    "processed": "1"
}

Returns a confirmation that the synonyms were successfully populated.

Attribute	Description
`success` Boolean	If `success` is true, the Library is successfully populated. Otherwise an error is returned.
`processed` Integer	Count of the total number of Records with which the Library has been populated.

Populating Locations Library

This POST method allows to populate the Locations Library in a single API call.

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/libraries/populate"

Endpoint: POST rest/v2/libraries/populate

Request

{
    "libraries": [{
        "locations": [{
                "riskLevel": "Blacklisted Country",
                "iso2": "AF",
                "active": true
            },
            {
                "riskLevel": "Blacklisted Region",
                "ctrp": "Crimea",
                "active": true
            }
        ]
    }]
}

Attribute	Description	Required
`locations` Array of Synonym Objects	Set of Locations used to populate the Library.	Yes
`riskLevel` String	Risk level based on the impact and likelihood ranking of the location risk.	No
`ctrp` String	Cities, Towns, Regions & Ports.	No
`iso2` String	Country in ISO 3166-alpha 2 format.	No
`active` Boolean	If `active` is true, the record is active and will be used for detection. If `active` is false, the record is not active and won't be used for detection. If `active` is not provided, Screena will set the parameter at true.	No

Response Attributes

Response

{
    "responseHeader": {
        "requestID": "c779f2c29b054066b6c03d4da903dc29",
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "success": true,
    "processed": "1"
}

Returns a confirmation that the synonyms were successfully populated.

Attribute	Description
`success` Boolean	If `success` is true, the Library is successfully populated. Otherwise an error is returned.
`processed` Integer	Count of the total number of Records with which the Library has been populated.

Library Bulk Importing

This POST method allows to import bulk data into Screena Libraries.

Request Attributes

curl -s -X POST \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: multipart/form-data" \
   -F 'upload_file=@/path/to/file' \
   "https://screena.ai/rest/v2/libraries/bulk-import"

Endpoint: POST rest/v2/libraries/bulk-import

Response Attributes

Response

{
    "responseHeader": {
        "responded": "2021-05-08T10:44:57.458Z"
    },
    "taskID": "TSK2054093905-1620470697458"
}

Returns a confirmation message that the asynchronous batch process was successfully started and a taskID is allocated.

How it works — The import is done through a file deposited in a directory accessible by Screena.

We recommend to use the JSON format, but CSV is also accepted by the application.

If you use the JSON format, there is nothing special to do, just specify the name of the Library where the records shall be imported.

To import data into Screena Librairies using CSV files, you must respect our CSV file specifications, which are extremely flexible:

The CSV file should be named after the library where the data will be imported. For example, if the data is being imported into the locations library, the CSV file should be named "locations.csv".
The CSV file shall be encoded in UTF-8.
The order of the fields in the CSV file is not important.
The delimiter between fields is the pipe.
The name of the fields is identical between JSON and CSV.

The below provides a CSV example to import data into the locations library:

iso2|ctrp|riskLevel
AF||Blacklisted Country
BY||Blacklisted Country
CU||Blacklisted Country
KP||Blacklisted Country
DJ||Blacklisted Country
IR||Blacklisted Country
LB||Blacklisted Country
MM||Blacklisted Country
SO||Blacklisted Country
SD||Blacklisted Country
SY||Blacklisted Country
TN||Blacklisted Country
VE||Blacklisted Country
|Labuan|Blacklisted CTRP

Browsing Libraries

This GET method allows to retrieve all entries of a Library.

Request Attributes

curl -s -X GET \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   "https://screena.ai/rest/v2/libraries/suffixes"

Endpoint: GET rest/v2/libraries/{library}

The query string is sent in the URL of the GET request. You need to pass the relevant library into the query string too (either "prefixes", "suffixes", "stopwords", "synonyms", or "locations").

Response Attributes

Response

{
    "responseHeader": {
        "responded": "2020-05-07T06:07:23.171Z"
    },
    "libraries": [{
        "suffixes": [{
                "value": "LLC",
                "entityTypes": ["organization"],
                "active": true
            },
            {
                "value": "Jr",
                "entityTypes": ["individual"],
                "sex": "M",
                "active": true
            }
        ]
    }]
}

Attribute	Description
`dataID` String	Unique Identifier of the Library record.
`value` String	Value of the Prefix, Suffix, Stopword, or Synonym.
`altValues` Array of Strings	Alternative values for a Synonym. Only applicable to Synonyms.
`entityTypes` String	Types of named-entity to which the value applies. Refer to Named-Entities Objects for more info.
`sex` String	Sex related to the Prefix, Suffix or Synonym. Only applicable to an individual.
`active` Boolean	If `active` is true, the record is active and will be used for normalization and gender detection. If `active` is false, the record is not active and won't be used for normalization and gender detection. If `active` is not provided, Screena will set the parameter at true.

Toolbox

About

One of the features of Screena's API is the provision of specific endpoints that are designed to provide users with a toolbox intended to help them execute specific tasks that can be useful on a day-to-day basis.

Retrieving Keywords

This GET method allows to retrieve all Keywords of a specified Dataset in a single API call.

Request Attributes

curl -s -X GET \
   -H "X-Screena-API-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -H "Accept: application/json" \
   -H "Cache-Control: no-cache" \
   -d '{your_json_data}' \
   "https://screena.ai/rest/v2/datasets/keywords/OFAC SDN"

Endpoint: GET rest/v2/datasets/keywords/{label}

The query string is sent in the URL of the GET request. You need to pass the relevant label into the query string too (e.g., the label of the dataset from which you wish to retrieve all keywords).

Response Attributes

Response

{
    "responseHeader": {
        "responded": "2023-05-09T06:35:11.379Z"
    },
    "datasets": [{
        "label": "OFAC SDN",
        "active": true,
        "keywords": [
            "CUBA",
            "SDGT",
            "SYRIA",
            "SDNT",
            "IRAN",
            "IRAN-EO13902",
            "IFSR",
            "IRGC",
            "FTO",
            "SDNTK",
            "ILLICIT-DRUGS-EO14059",
            "ZIMBABWE",
            "BALKANS",
            "IRAQ2",
            "DRCONGO",
            "NPWMD",
            "IRAN-CON-ARMS-EO",
            "DPRK2",
            "DARFUR",
            "NS-PLC",
            "BELARUS",
            "IRAN-HR",
            "HRIT-IR",
            "ELECTION-EO13848",
            "IRAQ3",
            "LEBANON",
            "SOMALIA",
            "HRIT-SY",
            "CAR",
            "IRAN-TRA",
            "VENEZUELA",
            "IFCA",
            "TCO",
            "RUSSIA-EO14024",
            "IRAN-EO13876",
            "CYBER2",
            "DPRK",
            "LIBYA2",
            "SYRIA-EO13894",
            "ISA",
            "DPRK3",
            "MAGNIT",
            "«Al-Qaïda», Taliban",
            "UKRAINE-EO13660",
            "UKRAINE-EO13661",
            "SOUTH SUDAN",
            "UKRAINE-EO13662",
            "RUSSIA-EO14065",
            "YEMEN",
            "UKRAINE-EO13685",
            "VENEZUELA-EO13850",
            "HIFPAA",
            "LIBYA3",
            "PEESA-EO14039",
            "CAATSA - RUSSIA",
            "HOSTAGES-EO14078",
            "BALKANS-EO14033",
            "DPRK4",
            "GLOMAG",
            "BURMA-EO14014",
            "IRAN-EO13871",
            "SSIDES",
            "NICARAGUA",
            "VENEZUELA-EO13884",
            "NICARAGUA-NHRAA",
            "IRAN-EO13846",
            "MALI-EO13882",
            "DPRK-NKSPEA",
            "CAATSA - IRAN",
            "SYRIA-CAESAR",
            "HK-EO13936",
            "BELARUS-EO14038",
            "PEESA",
            "ETHIOPIA-EO14046",
            "Belarus",
            "Yugoslavia",
            "Iraq",
            "Sudan",
            "Congo",
            "Guinea",
            "North Korea",
            "Liberia",
            "Libya",
            "Guinea-Bissau",
            "Côte d’Ivoire",
            "Somalia",
            "Iran",
            "Syria",
            "Zimbabwe",
            "South Sudan",
            "Myanmar",
            "Situation in Ukraine",
            "Central African Republic",
            "Yemen",
            "Burundi",
            "Venezuela",
            "Nicaragua",
            "Mali",
            "Haiti"
        ]
    }]
}

Attribute	Description
`label` String	Name of the Dataset, which shall be unique.
`active` Boolean	If `active` is true, the dataset and all the Records contained inside are active and can be searched and matched upon. If `active` is false, the dataset and all the Records contained inside can't be matched or searched.
`keywords` Array of Strings	Words or phrases that are associated with the dataset and all the Records contained inside and that describe information related to them. Typically in the context of Financial Crime Compliance, sanction regimes or law enforcement agencies’ programs (e.g., “Al-Qaida” or “White Collar Crimes”) are referred to as keywords.

Watchlists

About Watchlists

Screena offers native support for several open source global watchlists, including lists of sanctioned individuals, law enforcement databases, and politically exposed persons. Our watchlists are regularly updated to ensure that you have access to the most current information.

To see which public lists are currently available, please refer to our official set of Supported Watchlists published in our Help Center.

Datasets

{
    "dataset": {
        "label": "OFAC SDN",
        "category": "SANCTION",
        "dateOfPublication": "2023-05-02T00:00:00",
        "dateOfUpload": "2023-05-09T08:10:29.172"
    }
}

The following table lists all of the possible child attributes for dataset.

Attribute	Description	Required
`label` String	Name of the Dataset, which shall be unique.	Yes
`category` String	Category is used for organizing the Datasets into groups that can be categorized in some way similar to each other.	No
`dateOfPublication` String	Latest official Publication Date/Time by the owner of the source. Only returned for the Datasets included in our official set of supported Watchlists. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.	No
`dateOfUpload` String	Latest Upload Date/Time into the Screena Firm repository. Only returned for the Datasets included in our official set of supported Watchlists. Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.	No

Errors

Requests can fail for various reasons. They are categorized by types of errors.

HTTP Status

Status	Meaning
400	Bad Request - The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).
401	Unauthorized - Your API key is wrong.
404	Not Found - The specified API could not be found.
405	Method Not Allowed - You tried to access the API with an invalid method.
406	Not Acceptable - You requested a format that isn't json.
410	Gone - The method requested has been removed from our servers.
418	I'm a teapot.
422	Unprocessable Entity - The server understands the content type of the request entity but was unable to process the contained instructions. For example, this error condition may occur if the request body contains well-formed (i.e., syntactically correct), but semantically erroneous instructions.
429	Too Many Requests - You're requesting too many things in parrallel! Slow down!
500	Internal Server Error - We had a problem with our server. Try again later.
503	Service Unavailable - We're temporarily offline for maintenance. Please try again later.

Response: Typical example of an error

{
    "timestamp": "2020-09-01T12:50:29.258Z",
    "status": "400",
    "error": "Bad Request",
    "message": "SURNAME IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 255 CHARACTERS",
    "path": "/rest/v2/name-match"
}

Error Messages

Parameter	Message	HTTP Status
`requestID`	REQUEST ID IS NOT CONFORM, SHALL BE IN THE RANGE FROM 20 TO 200 CHARACTERS	400
`requestID`	REQUEST ID VALUE IS ALREADY USED	400
`apiKey`	UNAUTHORIZED - CHECK YOUR API KEY (MISSING OR WRONG)	401
`dataID`	DATA ID IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 200 CHARACTERS	400
`entityType`	INVALID ENTITY TYPE, CHECK POSSIBLE ENTITY TYPE VALUES	400
`fullName`	FULL NAME IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 255 CHARACTERS. IF YOU'RE NAME IS LONGER THAN ADOLPH BLAINE CHARLES DAVID EARL FREDERICK GERALD HUBERT IRVIN JOHN KENNETH LLOYD MARTIN NERO OLIVER PAUL QUINCY RANDOLPH SHERMAN THOMAS UNCAS VICTOR WILLIAM XERXES YANCY WOLFESCHLEGELSTEINHAUSENBERGERDORFF, GIVE US A CALL ! IF YOU'RE THE MAN WITH NO NAME YOU SHOULD BE IN THE WILD WEST AND NOT IN SOFTWARE DATABASES !	400
`fullName`	FULL NAME WITH PARSED NAMES, SHALL NOT BE PROVIDED IF ANY OF THE FOLLOWING ATTRIBUTE IS PROVIDED WITHIN THE SAME BLOCK: SURNAME, GIVEN NAME, FATHER NAME, MOTHER NAME	400
`surname`	SURNAME IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 255 CHARACTERS	400
`surname`	SURNAME IS NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: INDIVIDUAL, UNKNOWN	422
`givenName`	GIVEN NAME IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 255 CHARACTERS. IF YOU'RE GIVEN NAME IS LONGER THAN RHOSHANDIATELLY-NESHIAUNNVESHENK KOYAANFSQUATSIUTY GIVE US A CALL !	400
`givenName`	GIVEN NAME IS NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: INDIVIDUAL, UNKNOWN	422
`fatherName`	FATHER NAME IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 255 CHARACTERS	400
`fatherName`	FATHER NAME IS NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: INDIVIDUAL, UNKNOWN	422
`motherName`	MOTHER NAME IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 255 CHARACTERS	400
`motherName`	MOTHER NAME IS NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: INDIVIDUAL, UNKNOWN	422
`threshold`	INVALID THRESHOLD VALUE, SHALL BE A NUMBER BETWEEN 0 AND 1 WITH 2 DECIMAL PLACES AFTER THE DECIMAL POINT	400
`sex`	INVALID SEX, CHECK POSSIBLE SEX VALUES	400
`sex`	SEX IS NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: INDIVIDUAL, UNKNOWN	422
`date`	INVALID DATE, SHALL BE A VALID DATE VALUE/FORMAT	422
`streetName`	STREET NAME IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 255 CHARACTERS	400
`streetNumber`	STREET NUMBER IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 10 CHARACTERS	400
`street`	STREET IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 255 CHARACTERS	400
`poBox`	PO BOX IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 40 CHARACTERS	400
`zipCode`	ZIP CODE IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 40 CHARACTERS	400
`city`	CITY IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 100 CHARACTERS	400
`state`	STATE IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 20 CHARACTERS	400
`country`	INVALID COUNTRY, SHALL BE A VALID ISO 3166-1 ALPHA-2 VALUE	422
`nationalities`	NATIONALITY IS NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: INDIVIDUAL, UNKNOWN	400
`datesOfBirth`	DATES OF BIRTH ARE NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: INDIVIDUAL, UNKNOWN	422
`datesOfRegistry`	DATES OF REGISTRY NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: ORGANIZATION	422
`countriesOfRegistry`	COUNTRIES O FREGISTRY NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: ORGANIZATION	422
`datesOfBuild`	DATES OF BUILD NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: VESSEL	422
`flags`	FLAGS ARE NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: VESSEL	422
`entityTypeAlgo`	INVALID ENTITY TYPE ALGO, CHECK POSSIBLE ENTITY TYPE ALGO VALUES	400
`entityTypeAlgo`	INVALID INCLUDE/EXCLUDE OPTION FOR ENTITY TYPE ALGO, CHECK POSSIBLE ENTITY TYPE OPTION VALUES	422
`sexAlgo`	INVALID SEX ALGO, CHECK POSSIBLE SEX ALGO VALUES	400
`dateOfBirthAlgo`	INVALID DATE OF BIRTH ALGO, CHECK POSSIBLE DATE OF BIRTH ALGO VALUES	400
`placeOfBirthAlgo`	INVALID PLACE OF BIRTH ALGO, CHECK POSSIBLE PLACE OF BIRTH ALGO VALUES	400
`nationalityAlgo`	INVALID NATIONALITY ALGO, CHECK POSSIBLE NATIONALITY ALGO VALUES	400
`addressAlgo`	INVALID ADDRESS ALGO, CHECK POSSIBLE ADDRESS ALGO VALUES	400
`fullAddress`	FULL ADDRESS WITH PARSED ADDRESSES, SHALL NOT BE PROVIDED IF ANY OF THE FOLLOWING ATTRIBUTE IS PROVIDED WITHIN THE SAME BLOCK: STREET NUMBER, STREET NAME, STREET, PO BOX, ZIP CODE, CITY, STATE	400
`dateOfRegistryAlgo`	INVALID DATE OF REGISTRY ALGO, CHECK POSSIBLE DATE OF REGISTRY ALGO VALUES	400
`placeOfRegistryAlgo`	INVALID PLACE OF REGISTRY ALGO, CHECK POSSIBLE PLACE OF REGISTRY ALGO VALUES	400
`dateOfBuildAlgo`	INVALID DATE OF BUILD ALGO, CHECK POSSIBLE DATE OF BUILD ALGO VALUES	400
`flagAlgo`	INVALID FLAG ALGO, CHECK POSSIBLE FLAG ALGO VALUES	400
`nullMatch`	NULL-MATCH IS NOT CONFORM, SHALL BE A BOOLEAN VALUE	400
`libraries`	DUPLICATE LIBRARY ENTRY	422
`label`	LABEL IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 999 CHARACTERS	400
`label`	LABEL VALUE IS ALREADY USED	422
`value`	VALUE IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 999 CHARACTERS	400
`altValues`	ALT. VALUE IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 999 CHARACTERS	400
`cultureCodes`	INVALID CULTURE CODE, SHALL BE A VALID ISO 639-1 VALUE	422
`cultureCodes`	CULTURE CODE IS NOT APPLICABLE, SHALL NOT BE PROVIDED IF ENTITY TYPE IS DIFFERENT FROM: INDIVIDUAL, UNKNOWN	422
`prefixes`	THE COMBINATION OF THE FOLLOWING ATTRIBUTES MUST BE UNIQUE: VALUE; ENTITY TYPE	422
`suffixes`	THE COMBINATION OF THE FOLLOWING ATTRIBUTES MUST BE UNIQUE: VALUE; ENTITY TYPE	422
`stopwords`	THE COMBINATION OF THE FOLLOWING ATTRIBUTES MUST BE UNIQUE: VALUE; ENTITY TYPE; CULTURE CODES	422
`synonyms`	THE COMBINATION OF THE FOLLOWING ATTRIBUTES MUST BE UNIQUE: VALUE; ENTITY TYPE; CULTURE CODES; SEX	422
`dataset`	THE DATASET PROVIDED DOESN'T EXIST	422
`number`	NUMBER IS NOT CONFORM, SHALL BE IN THE RANGE FROM 1 TO 200 CHARACTERS	400
`narrative`	NARRATIVE SHALL BE PROVIDED WITH NO OTHER ATTRIBUTES (BUT DATAID)	400