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

API Description​

Objective​

API URL​

API Endpoint​

Supported Regions​

Overview​

Method - POST​

Authentication​

Headers​

Inputs​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​