AML Screening

The following document describes the AML Screening module and the responses it returns.

Description

Objective

The AML Screening module screens user information against major sanction lists (such as UNSC, OFAC, Interpol, IRDAI, and FIU) and the Politically Exposed Persons (PEP) database. You can customize which databases and filters are used to match your screening requirements.

Input	Output
Name, date of birth, country ID, search profile, ID number, ID type.	Screening result with action (pass, manualReview, or fail), matched hits with source details, and match metadata. See Success Response Details for the full list of output fields.

Supported Regions

The AML Screening module supports the following regions:

Region	Region Code
India	ind
USA	usa
Africa	zaf
Europe	irl
Singapore	sgp

Configurations

This module does not support any additional configurations.

Success Response

The following code snippet demonstrates a success response from the AML Screening module. The example shows a response for a valid request where multiple hits were found against the queried user.

{
  "statusCode": 200,
  "metaData": {
    "transactionId": "<Transaction_ID>",
    "requestId": "<Request_ID>"
  },
  "summary": {
    "action": "<Action_Taken>",
    "details": [
      {
        "code": 433,
        "message": "<Action_Message>"
      }
    ]
  },
  "result": {
    "hits": [
      {
        "name": "<Name_Of_Person>",
        "id": null,
        "updatedAt": "<Updated_At_Timestamp>",
        "createdAt": "<Created_At_Timestamp>",
        "aka": [],
        "sources": {
          "adverseMedia": [],
          "pep": [],
          "sanction": [],
          "warning": [
            {
              "name": "<Source_Name>",
              "url": "<Source_URL>",
              "countryCodes": "<Country_Code>",
              "dob": "<Date_Of_Birth>",
              "originalId": "<Original_ID>",
              "fullName": "<Full_Name>",
              "courtesyTitle": "<Courtesy_Title>",
              "firstName": "<First_Name>",
              "lastName": "<Last_Name>",
              "title": "<Title>",
              "pob": "<Place_Of_Birth>",
              "imageUrl": "<Image_URL>",
              "type": "<Type_Of_Entity>",
              "addressRemarks": "<Address_Remarks>"
            }
          ],
          "fitnessProbity": []
        },
        "associates": [],
        "yobMatch": true,
        "countryMatch": true,
        "dob": "<Date_Of_Birth>",
        "countries": "<Country_Name>",
        "nameMatch": "<Name_Match_Type>",
        "hitId": "<Hit_ID>",
        "idNumberMatch": false,
        "details": {
          "countryMatch": true,
          "yobMatch": true,
          "exactNameMatch": true,
          "dobExists": true,
          "countryExists": true,
          "idNumberMatch": false
        },
        "relevanceScore": 0
      },
      {
        "name": "<Name_Of_Person>",
        "id": null,
        "updatedAt": "<Updated_At_Timestamp>",
        "createdAt": "<Created_At_Timestamp>",
        "aka": [],
        "sources": {
          "adverseMedia": [],
          "pep": [
            {
              "name": "<Source_Name>",
              "url": "<Source_URL>",
              "countryCodes": "<Country_Code>",
              "originalId": "<Original_ID>",
              "fullName": "<Full_Name>",
              "firstName": "<First_Name>",
              "lastName": "<Last_Name>",
              "title": "<Title>",
              "sex": "<Gender>",
              "documents": "<Document_URL>",
              "pob": "<Place_Of_Birth>",
              "citizenship": "<Citizenship>",
              "constituency": "<Constituency>",
              "imageUrl": "<Image_URL>",
              "type": "<Type_Of_Entity>",
              "remarks": "<Remarks>",
              "address": "<Street_Address>",
              "city": "<City>",
              "postCode": "<Postal_Code>",
              "addressRemarks": "<Address_Remarks>"
            }
          ],
          "sanction": [],
          "warning": [],
          "fitnessProbity": []
        },
        "associates": [],
        "countryMatch": true,
        "dob": [],
        "countries": "<Country_Name>",
        "nameMatch": "<Name_Match_Type>",
        "hitId": "<Hit_ID>",
        "idNumberMatch": false,
        "details": {
          "countryMatch": true,
          "exactNameMatch": true,
          "countryExists": true,
          "idNumberMatch": false
        },
        "relevanceScore": 0
      },
      {
        "name": "<Name_Of_Person>",
        "id": null,
        "updatedAt": "<Updated_At_Timestamp>",
        "createdAt": "<Created_At_Timestamp>",
        "aka": [],
        "sources": {
          "adverseMedia": [],
          "pep": [
            {
              "name": "<Source_Name>",
              "url": "<Source_URL>",
              "countryCodes": "<Country_Code>",
              "originalId": "<Original_ID>",
              "fullName": "<Full_Name>",
              "firstName": "<First_Name>",
              "lastName": "<Last_Name>",
              "title": "<Title>",
              "sex": "<Gender>",
              "documents": "<Document_URL>",
              "citizenship": "<Citizenship>",
              "constituency": "<Constituency>",
              "politicalParty": "<Political_Party>",
              "type": "<Type_Of_Entity>",
              "remarks": "<Remarks>",
              "addressRemarks": "<Address_Remarks>"
            }
          ],
          "sanction": [],
          "warning": [],
          "fitnessProbity": []
        },
        "associates": [],
        "countryMatch": true,
        "dob": [],
        "countries": "<Country_Name>",
        "nameMatch": "<Name_Match_Type>",
        "hitId": "<Hit_ID>",
        "idNumberMatch": false,
        "details": {
          "countryMatch": true,
          "exactNameMatch": true,
          "countryExists": true,
          "idNumberMatch": false
        },
        "relevanceScore": 0
      },
      {
        "name": "<Name_Of_Person>",
        "id": null,
        "updatedAt": "<Updated_At_Timestamp>",
        "createdAt": "<Created_At_Timestamp>",
        "aka": [],
        "sources": {
          "adverseMedia": [],
          "pep": [
            {
              "name": "<Source_Name>",
              "url": "<Source_URL>",
              "countryCodes": "<Country_Code>",
              "originalId": "<Original_ID>",
              "fullName": "<Full_Name>",
              "courtesyTitle": "<Courtesy_Title>",
              "firstName": "<First_Name>",
              "lastName": "<Last_Name>",
              "title": "<Title>",
              "documents": "<Document_URL>",
              "citizenship": "<Citizenship>",
              "imageUrl": "<Image_URL>",
              "type": "<Type_Of_Entity>",
              "program": "<Program>",
              "addressRemarks": "<Address_Remarks>"
            }
          ],
          "sanction": [],
          "warning": [],
          "fitnessProbity": []
        },
        "associates": [],
        "countryMatch": true,
        "dob": [],
        "countries": "<Country_Name>",
        "nameMatch": "<Name_Match_Type>",
        "hitId": "<Hit_ID>",
        "idNumberMatch": false,
        "details": {
          "countryMatch": true,
          "exactNameMatch": true,
          "countryExists": true,
          "idNumberMatch": false
        },
        "relevanceScore": 0
      }
    ]
  }
}

Success Response Details

The following table outlines the details of the success response from the AML Screening module. Parameters are listed in the same order as they appear in the response.

Parameter	Type	Description
statusCode	integer	The HTTP status code of the request (e.g. 200)
metaData	object	Contains transaction and request details
metaData.transactionId	string	The unique identifier for the transaction
metaData.requestId	string	The system generated ID for the request
summary	object	Provides an overview of the action taken
summary.action	string	The system's verdict on the API call: indicates "manualReview," "pass," or "fail" based on matching criteria.
summary.details	array	This field lists the reasons for the action response. It has data only when the action is Manual Review.
summary.details[].code	integer	The numeric code representing the action
summary.details[].message	string	The message describing the action
result	object	Contains the details of the matched records
result.hits	array	List of matched individuals and their details
result.hits[].name	string	The name from the matching record in the database
result.hits[].id	null	The unique identifier for a matching record in the database. If there are no matching records found in the database against your search, this field will not return a value.
result.hits[].updatedAt	string	This timestamp represents the date and time when the user's profile was modified and updated in the database
result.hits[].createdAt	string	This timestamp represents the date and time when the user's profile was added to the database
result.hits[].aka	array	The known aliases or alternate names of the individual whose records were matched
result.hits[].sources	object	This is an object of source buckets such as adverseMedia, pep, sanction, warning, and fitnessProbity. Each bucket contains the source details and the related metadata extracted from that source.
result.hits[].sources.adverseMedia	array	The list of adverse media sources
result.hits[].sources.pep	array	The list of Politically Exposed Persons (PEP) sources
result.hits[].sources.sanction	array	The list of sanctions
result.hits[].sources.warning	array	The list of warning sources
result.hits[].sources.fitnessProbity	array	The list of fitness and probity sources
result.hits[].associates	array	List of associates linked to the matched individual
result.hits[].yobMatch	boolean	When present, indicates whether the year of birth matches between the request and the matched record
result.hits[].countryMatch	boolean	Indicates whether the country of the matched record matches the countryId provided in the request
result.hits[].dob	string or array	Date(s) of birth associated with the matched record
result.hits[].countries	string or array	The list of countries associated with the individual
result.hits[].nameMatch	string or array	This field lists the reasons behind the name match (e.g. "Exact name match")
result.hits[].hitId	string	The unique identifier provided by HyperVerge for a matching record
result.hits[].idNumberMatch	boolean	This field indicates whether the provided ID number (e.g., PAN number) matches any records within external sources, such as sanction lists, PEP databases, and other source buckets (e.g., sanction, adverse media, warning). A value of true indicates a match with one or more of these sources, while false indicates no matches were found.
result.hits[].details	object	Contains additional match details
result.hits[].details.countryMatch	boolean	Indicates whether the country of the matched record matches the request
result.hits[].details.yobMatch	boolean	When present, indicates whether the year of birth matches
result.hits[].details.exactNameMatch	boolean	This field indicates if there is an exact name match from the database
result.hits[].details.dobExists	boolean	When present, indicates whether a date of birth exists for the matched record
result.hits[].details.countryExists	boolean	This field indicates if the country is present in the details
result.hits[].details.idNumberMatch	boolean	Indicates whether the provided ID number matches the record
result.hits[].relevanceScore	number	The relevance score indicating the strength of the match

Response When Matches Are Found

When one or more matches are found (e.g. against PEP or sanction lists), the module returns a response with action set to manualReview (or fail depending on configuration) and populates result.hits.

{
  "statusCode": 200,
  "metaData": {
    "transactionId": "<Transaction_ID>",
    "requestId": "<Request_ID>"
  },
  "summary": {
    "action": "manualReview",
    "details": [
      {
        "code": 433,
        "message": "Found 1 hit(s)"
      }
    ]
  },
  "result": {
    "hits": [
      {
        "name": "<Name_Of_Person>",
        "id": null,
        "updatedAt": "<Updated_At_Timestamp>",
        "createdAt": "<Created_At_Timestamp>",
        "aka": [],
        "sources": {
          "adverseMedia": [],
          "pep": [],
          "sanction": [],
          "warning": [],
          "fitnessProbity": []
        },
        "associates": [],
        "countryMatch": true,
        "dob": [],
        "countries": "<Country_Name>",
        "nameMatch": "<Name_Match_Type>",
        "hitId": "<Hit_ID>",
        "idNumberMatch": false,
        "details": {
          "countryMatch": true,
          "exactNameMatch": true,
          "countryExists": true,
          "idNumberMatch": false
        },
        "relevanceScore": 0
      }
    ]
  }
}

The fields inside result.hits[] are described in the Success Response Details table above.

Error Responses

When the module input is invalid or the request fails, you receive an error response. Example (server error):

{
  "status": "failure",
  "statusCode": 500,
  "error": {
    "message": "Internal Server Error"
  }
}

Error Response Details

An error response contains a failure status with a relevant status code and error message. The following table lists error responses from the AML Screening module.

Status Code	Error Message	Error Description	Error Resolution
400	Input Validation Error: requires property "name"	The mandatory name field is missing in the input.	Ensure the name parameter is provided in the module input
401	Missing/Invalid credentials	The request is missing mandatory credentials or has invalid credentials.	Verify your integration credentials with the HyperVerge team
500	Internal Server Error	There was an error with HyperVerge's server.	Contact the HyperVerge team for resolution