NAV Navbar
Shell

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 Versions

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

The API documentation was last updated on May 10th, 2021.

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
Screena Firm POST rest/v2/dataset-search
rest/v2/dataset-search-engine
Searching Datasets
Integrating Search Engines
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 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 Libraries
Populating Suffixes Library
Populating Stopwords Library
Populating Synonyms Library
Screena Firm GET rest/v2/libraries/{library} Browsing Libraries

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

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 80%.

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.80.
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.94,
  "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.

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.80.
Refer to Name-Matching Algorithms for more info.
No

Response Attributes

Response

{
 "responseHeader": {
  "requestID": "555-415-1337-00ub0oNGTSWTBKOLGLNR",
  "responded": "2021-05-07T06:13:09.635Z"
 },
 "results": [{
   "matchType": "st_match",
   "score": 0.94,
   "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.91,
   "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

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
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
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.80.
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

Response Attributes

Response

{
 "responseHeader": {
  "requestID": "c779f2c29b054066b6c03d4da903dc33",
  "responded": "2021-05-12T15:40:17.631Z"
 },
 "results": [{
   "matchType": "st_match",
   "score": 0.98,
   "sourceData": [{
    "dataID": "174",
    "entityType": "individual",
    "names": [{
     "surname": "callas",
     "givenName": "maria",
     "normalized": "maria callas"
    }],
    "sex": "F",
    "cultureCodes": [
     "en"
    ],
    "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.04,
   "unmatched": [
    "names"
   ],
   "sourceData": [{
    "dataID": "174",
    "entityType": "individual",
    "names": [{
     "surname": "callas",
     "givenName": "maria",
     "normalized": "maria callas"
    }],
    "sex": "F",
    "cultureCodes": [
     "en"
    ],
    "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.05,
   "unmatched": [
    "names"
   ],
   "sourceData": [{
    "dataID": "174",
    "entityType": "individual",
    "names": [{
     "fullName": "Anna Maria Sophia Cecilia Kaloyeropoulou",
     "normalized": "anna maria sophia cecilia kaloyeropoulou"
    }],
    "sex": "F",
    "cultureCodes": [
     "en"
    ],
    "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.26,
   "unmatched": [
    "names"
   ],
   "sourceData": [{
    "dataID": "174",
    "entityType": "individual",
    "names": [{
     "fullName": "Anna Maria Sophia Cecilia Kaloyeropoulou",
     "normalized": "anna maria sophia cecilia kaloyeropoulou"
    }],
    "sex": "F",
    "cultureCodes": [
     "en"
    ],
    "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"
    }]
   }]
  }
 ]
}

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 not ignored.
Refer to Sexes and Genders for more info.
nationalities
Array of Location Objects
Nationality for an individual, only returned if not ignored.
See child attributes for Countries.
datesOfBirth
Array of Date Objects
Date of birth for an individual, only returned if not ignored.
Refer to Dates for more info.
placesOfBirth
Array of Location Objects
Place of birth for an individual, only returned if not ignored.
See child attributes for Places.
addresses
Array of Location Objects
Address for an individual, only returned if not ignored.
See child attributes for Addresses.
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
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
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.80.
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.
No
addressAlgo
Algorithm Object
The type of algorithms used for matching countries.
Refer to Date-Matching Algorithms for more info.
No

Response Attributes

Response

{
 "responseHeader": {
  "requestID": "c779f2c29b054066b6c03d4da903dc34",
  "responded": "2021-05-05T10:08:01.722Z"
 },
 "results": [{
   "matchType": "st_match",
   "score": 0.98,
   "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.98,
   "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
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.
datesOfRegistry
Array of Date Objects
This is the date of registration for a organization, only returned if not ignored.
See child attributes for Dates.
placesOfRegistry
Array of Location Objects
This is the place of registration for an organization, only returned if not ignored.
See child attributes for Places.
addresses
Array of Location Objects
Address for an organization, only returned if not ignored.
See child attributes for Addresses.
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
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.80.
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

Response Attributes

Response

{
 "responseHeader": {
  "requestID": "c779f2c29b054066b6c03d4da903dc34",
  "responded": "2020-05-27T17:20:58.820Z"
 },
 "results": [{
  "matchType": "st_match",
  "score": 0.99,
  "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 not ignored.
See child attributes for Countries.
datesOfBuild
Array of Date Objects
Date at which the vessel was completed, only returned if not ignored.
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):

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

Response Attributes

Response attributes are similar than those provided when matching individuals.

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.

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",
  "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.
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
Integer
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"
 }]
}

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 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.

(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.

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

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
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

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
datesOfRegistry
Array of Date Objects
This is the date of registration for a organization, can be many.
Refer to Dates for more info.
No
placesOfRegistry
Array of Location Objects
This is the 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
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
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
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.

Bulk Importing

This POST method allows to start the 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.

(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).

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 Periodic 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

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": [{
  "records": [{
   "dataID": "15999",
   "created": "2020-04-17T14:30:15.321+01:00",
   "updated": "2020-04-21T17:33:25.441+01:00",
   "revision": 2,
   "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"
   }],
   "label": "COMPANY 1",
   "revision": 4,
   "active": true,
   "updated": "2021-02-26T18:28:40.923",
   "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.
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 Periodic Screening.
Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
category
String
Dataset category. It can be a watchlist, a grey list, a customer list, etc.
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.
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.

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.
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 Periodic Screening.
Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
category
String
Dataset category. It can be a watchlist, a grey list, a customer list, etc.
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.
datesOfRegistry
Array of Date Objects
Date of registration for a organization, can be many.
Refer to Dates for more info.
placesOfRegistry
Array of Location Objects
Place of registration 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.
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.

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.
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 Periodic Screening.
Provided in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.
category
String
Dataset category. It can be a watchlist, a grey list, a customer list, etc.
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.
sources
Array of Strings
Any source from which information about the vessel comes, arises, or is obtained.
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.

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.

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: 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.80.
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"
     }
    ],
    "label": "COMPANY 1"
   }]
  },
  {
   "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"
     }
    ],
    "label": "COMPANY 1"
   }]
  }
 ]
}
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:
targetData
Array of Data Objects
Get the same Response Attributes that are available in Screena Plus:

Integrating Search Engines

Screena is designed to integrate with third-party search engines for named-entities information retrieval.

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

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

{
 "queries": [{
  "sourceData": [{
   "names": [{
    "fullName": "emmanuel macron"
   }]
  }],
  "threshold": 0.57
 }],
 "paginationRequest": {
  "pageNumber": 0,
  "maxPerPage": 2,
  "calculateSearchStats": true
 }
}
Attribute What can be used ? Required
sourceData
Array of Data Objects
Use All the Request Attributes that are available in Screena Plus: 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.80.
Refer to Name-Matching Algorithms for more info.
No
- All available algorithms.
Refer to Algorithms for more information.
No

Response Attributes

Response

{
 "numberOfObjects": 2,
 "searchStats": {
  "numberOfPeps": 2,
  "numberOfSanctions": 0,
  "numberOfWanteds": 0,
  "numberOfAll": 2,
  "numberOfOrganizations": 0,
  "numberOfIndividuals": 2,
  "numberOfUnknown": 0,
  "numberOfVessels": 0,
  "foundDataset": [
   "WORLD LEADERS"
  ]
 },
 "responseHeader": {
  "requestID": "GEN2054093905-1632379305309",
  "responded": "2021-09-23T06:41:45.309Z"
 },
 "results": [{
   "matchType": "st_match",
   "score": 1.00,
   "matchingNames": [{
    "fullName": "Emmanuel MACRON",
    "normalized": "emmanuel macron"
   }],
   "sourceData": [{
    "entityType": "unknown",
    "names": [{
     "fullName": "emmanuel macron",
     "normalized": "emmanuel macron"
    }],
    "sex": "u",
    "cultureCodes": [
     "en",
     "fr"
    ]
   }],
   "targetData": [{
    "dataID": "AD-245342216",
    "entityType": "individual",
    "names": [{
     "fullName": "Emmanuel MACRON",
     "normalized": "emmanuel macron"
    }],
    "sex": "u",
    "cultureCodes": [
     "en",
     "fr"
    ],
    "active": true,
    "sources": [
     "https://www.cia.gov/resources/government/andorra/"
    ],
    "titles": [
     "Head of State (Co-Prince)"
    ],
    "nationalities": [{
     "country": "AD"
    }],
    "label": "WORLD LEADERS"
   }]
  },
  {
   "matchType": "st_match",
   "score": 1.00,
   "matchingNames": [{
    "fullName": "Emmanuel MACRON",
    "normalized": "emmanuel macron"
   }],
   "sourceData": [{
    "entityType": "unknown",
    "names": [{
     "fullName": "emmanuel macron",
     "normalized": "emmanuel macron"
    }],
    "sex": "u",
    "cultureCodes": [
     "en",
     "fr"
    ]
   }],
   "targetData": [{
    "dataID": "FR-245342216",
    "entityType": "individual",
    "names": [{
     "fullName": "Emmanuel MACRON",
     "normalized": "emmanuel macron"
    }],
    "sex": "u",
    "cultureCodes": [
     "en",
     "fr"
    ],
    "active": true,
    "sources": [
     "https://www.cia.gov/resources/government/france/"
    ],
    "titles": [
     "Pres."
    ],
    "nationalities": [{
     "country": "FR"
    }],
    "label": "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 Data 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:
targetData
Array of Data Objects
Get the same Response Attributes that are available in Screena Plus:
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.

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.80.
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.

Periodic Screening

Where either source or target Datasets change frequently, Periodic 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:

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:

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

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

  1. Full results (i.e. results predicted as positives as well as resultats predicted as negatives).
  2. Results predicted as positives.
  3. 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:

  1. GET rest/v2/dataset-match/{taskID} : Getting full Results.
  2. GET rest/v2/dataset-match/positives/{taskID} : Getting Results predicted as positives.
  3. 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.00,
  "sourceData": [{
   "dataID": "110406",
   "entityType": "unknown",
   "names": [{
    "fullName": "Aali Akber Tahmaesebi",
    "normalized": "aali akber tahmaesebi"
   }],
   "cultureCodes": ["ar"],
   "revision": 1,
   "label": "thoughtbox-source",
   "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"],
   "revision": 1,
   "label": "EU",
   "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.
revision
Integer
Revision of the data Record, which keeps history of every change.
label
String
Name of your Dataset as you specified it.
created
String
Creation Date of the Record.
Shall be provided in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.
updated
String
Update Date of the Record.
Shall be provided in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.
lastMatched
String
Date/Time when the Record was last matched.
This field is used to manage deltas in Periodic Screening.
Shall be provided in ISO 8601 format: YYYY-MM-DD or YYYY-MM-DD/YYYY-MM-DD.
sourceData
Array of Data Objects
Get the same Response Attributes that are available in Screena Plus:
targetData
Array of Data Objects
Get the same Response Attributes that are available in Screena Plus:

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.
location
Lab
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.

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:

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:

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:

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
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": [{
        "number": "86YH34567",
        "type": "PP",
        "issuingCountry": {
            "country": "FR"
        },
        "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. No
issuingCountry
String
The country which has issued the passport or the document in reference in ISO 3166-alpha 2 format. No
dateOfIssue
String
The date on which a government body issued the Identity Document. No
dateOfExpiry
String
The date on which the Identity Document expires. No

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

Value Description
PP Passport
IC ID card
SS Social Security card
DL Driver's license
BC Birth certificate
DC Death certificate
OT Other identity documents
XX Unknown

Algorithms

Parametrization

{
 "type": "exact_match",
 "nullMatch": true
}

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

Normalization

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:

Binary-Matching Algorithms

{
  "sexAlgo": {
   "type": "exact_match",
   "nullMatch": true
  }
}

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

Algorithm Types

Value Description
exact_match
Default
Exactly match the attribute.
ignore The attribute is ignored for the match. If a field is empty, 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:

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:

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:

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:

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 94% 57% 0% 71%
al-qaida in the arabian peninsula/ansar al-sharia //al-qa'ida in the arabian peninsula 87% 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 80% which provides an excellent balance betweeen precision and recall. 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:

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:

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

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": 1.00,
  "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 Librairies.

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.

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 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 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 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.

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.

Simply replace {library} in the URL by either "prefixes", "suffixes", "stopwords", or "synonyms".

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 Suffix.
Only applicable to 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.

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, SHALL BE A NUMBER 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 40 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 SEX ALGO VALUES 400
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
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

API Terms of Service

First of all, thanks again for using Screena’s API to build an application !

By accessing or using our API, you are agreeing to the terms below. If there is a conflict between these terms and additional terms applicable to the Screena API, the additional terms will control for that conflict. Collectively, we refer to the terms below, any additional terms, terms within the accompanying API documentation, and any applicable policies and guidelines as the "Terms". You agree to comply with the Terms and that the Terms control your relationship with us. So please read all the Terms carefully. If you use the API as an interface to, or in conjunction with other Screena products or services, then the terms for those other products or services also apply.

Under the Terms, "Screena" means Screena SAS (currently under registration) unless set forth otherwise in additional terms applicable for a given API. We may refer to "Screena" as "we", "our", or "us" in the Terms.

No Warranty

All services and content of the Screena API are provided under Screena Terms on an "as is" basis, without warranty of any kind, either expressed or implied, including, without limitation, warranties that the provided services and content are free of defects, merchantable, fit for a particular purpose or non-infringing.

The entire risk as to the quality and performance of the provided services and content is with you. In no event shall Screena be liable for any damages whatsoever arising out of or in connection with the use or performance of the services.

Should any provided services and content prove defective in any respect, you (not the initial developer, author or any other contributor) assume the cost of any necessary servicing, repair or correction. This disclaimer of No Warranty constitutes an essential part of these Terms. No use of any services and content of Screena is authorized hereunder except under this disclaimer.

Ownership

Screena retains all rights, title and interest in and to its API, Products, Upgrades, Documentation, and any other related documentation:

The Screena software, API or any other materials provided by Screena (including without limitation all patents, copyrights, trademarks, trade secrets and other intellectual or industrial property rights embodied in any of the foregoing) remain its exclusive property.

Screena does not acquire ownership in your API Clients, and by using our APIs, you do not acquire ownership of any rights in our APIs or the content that is accessed through our APIs.

Compliance with Law

You will comply with all applicable law, regulation, and third party rights (including without limitation laws regarding the import or export of data or software, privacy, and local laws).

You will not use the APIs to encourage or promote illegal activity or violation of third party rights.

You will not violate any other terms of service with Screena (or its affiliates).

You will require your end users to comply with (and not knowingly enable them to violate) applicable law, regulation, and the Terms.

API Limitations

Screena sets and enforces limits on your use of the APIs (e.g. limiting the number of API requests that you may make or the number of users you may serve), in our sole discretion. You agree to, and will not attempt to circumvent, such limitations documented with each API. If you would like to use any API beyond these limits, you must obtain Screena's express consent (and Screena may decline such request or condition acceptance on your agreement to additional terms and/or charges for that use).

To seek such approval, contact the relevant Screena API team for information.

Non-Exclusivity

The Terms are non-exclusive. You acknowledge that Screena may develop products or services that may compete with the API Clients or any other products or services.

Trademark & Brand Usage

If you plan to utilize Screena’s trademark or branding in the visual design of your application or website, please adhere to Screena’s Trademark & Brand guidelines.

Please take note of the following:

“Screena” cannot be the first word in your application’s name. It can be used in the name of your app, though. For instance “x for Screena” or “x with Screena”, etc. This makes it clear that your application is created by you and not by Screena. You must clearly state that your application is “not created by, affiliated with, or supported by Screena” in your application description. By using the Screena marks you agree to properly follow the above Trademark & Brand guidelines as well as our Terms of Service.

For further information please contact the Screena team.