AML Screening API

The following document highlights the details of the AML Screening API.

API Description

Objective

The AML Screening API 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, matched hits with source details, and match metadata. The complete list of output fields is available in the Success Response Details section

API URL

https://<Region_Code>.thomas.hyperverge.co/v1/amlSearch

API Endpoint

amlSearch

Supported Regions

The AML Screening API URL accepts any of the following region code values against the regionCode placeholder.
For example, "https://ind-engine.thomas.hyperverge.co/v1/amlSearch".

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

Overview

The AML Screening API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should upload all images and files as form-data through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the AML Screening API.

Headers

Header	Mandatory / Optional	Description	Input Format
Content-Type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	Application ID shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	Application Key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey.	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the AML Screening API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
name	Mandatory	string	The full name of the user separated by spaces	Not Applicable	Not Applicable
dob	Optional	string	The date of birth of the user	DD-MM-YYYY	Not Applicable
countryId	Optional	string	This parameter accepts standard Alpha 3 Country Codes. If set, the AML Screening API also evaluates a country match for the record and returns the boolean result in the countryMatch field of the response body. It is an additional check that returns true if the matched entity's country is an exact match with your input. If not, it returns 'false' in the response.	Alpha 3 country code (e.g. IND, USA)	Not Applicable
searchProfile	Optional	string	The parameter enables support for AML search against custom sanctions and warning lists. You can configure multiple verification flows under AML for your business and select any of them based on your preference. The HyperVerge team creates and configures the searchProfile under the backend configuration against your appId; use this parameter only if you have configured multiple search profiles. If you pass the alphanumeric code from HyperVerge in the API call, it overwrites the default search profile for your appId.	Alphanumeric code provided by HyperVerge for the configured search profile	Not Applicable
idNumber	Selectively Optional*: It should be used in combination with the idType parameter, which is to be set to "PAN".	string	This parameter accepts the user's Permanent Account Number (PAN) for screening within the India region. This parameter acts as an additional filter to refine matching results.	PAN format: CCCCCDDDDC	Not Applicable
idType	Selectively Optional*: It should be used in combination with the idNumber parameter.	string	Specifies the type of identity document associated with the provided ID number. Currently, this parameter only supports the value "PAN" for use in the India region.	PAN	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the AML Screening API:

curl --location --request POST 'https://<Region_Code>.thomas.hyperverge.co/v1/amlSearch' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
    "name": "<Enter_name_of_the_user>",
    "dob": "<Enter_date_of_birth_of_the_user>",
    "idType": "<Enter_ID_Type>",
    "idNumber": "<Enter_PAN_number>",
    "countryId": "<Enter_country_ID>"
}'

Success Response

The following code snippet demonstrates a success response from the AML Screening API. 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 API. 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

Error Responses

The following code snippet demonstrates an error response from the AML Screening API (server error example):

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

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses from the AML Screening API:

Status Code	Error Message	Error Description	Error Resolution
400	Input Validation Error: requires property "name"	The mandatory name field is missing in the request.	Include the name parameter in the request body
401	Missing/Invalid credentials	The request is either missing the mandatory credentials or has invalid credentials.	Provide valid appId and appKey credentials in the request headers
500	Internal Server Error	There was an error with HyperVerge's server.	Please check the request headers and payload, or contact the HyperVerge team for resolution