Monitoring Report API

Objective

The Monitoring Report API retrieves a client's monitoring summary for a specific date, returning the total number of applications enrolled for monitoring as well as the existing ones if changes are observed in them. Additionally, it includes the history of changes with their respective timestamps.

info

Monitoring Reports are accessible within a 30-day window. These reports provide daily snapshots of activities recorded in the Monitoring Database, including updates to the Anti-Money Laundering (AML) Database enrolled by the client. This ensures that any relevant updates to the client's records in the AML Database are captured and included in the monitoring reports.

This access period is maintained due to the presence of Personally Identifiable Information (PII) in AML responses, which are included in the API Response.

API URL

https://ind.thomas.hyperverge.co/v1/amlMonitoringReport

API Endpoint

amlMonitoringReport

Overview

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

Authentication

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

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Allowed Values
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Input

The following table provides the complete information on the parameter used in the request body for the API calls.

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
queryDate	Date for which the monitoring JSON file is required	Mandatory	Format: YYYY-MM-DD	Not Applicable

Request

The following code shows a standard curl request for the API.

curl --location --request POST 'https://ind.thomas.hyperverge.co/v1/amlMonitoringReport' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "queryDate": "<YYYY-MM-DD_FORMAT>"
}'

Success Response

Records Monitored- No Hits Found

{
    "status": "success",
    "statusCode": 200,
    "metaData": {
        "transactionId": <Transaction_ID>,
        "requestId": <Request_ID>
    },
    "result": {
        "message": "Report Fetched Successfully",
        "metaData": {
            "recordsMonitored": 0,
            "needsReview": 0
        },
        "recordsToBeReviewed": []
    }
}

Records Monitored- Hits Found

{
  "metaData": {
    "recordsMonitored": "<Number_of_Records_Monitored>",
    "needsReview": "<Number_of_Records_Needing_Review>"
  },
  "recordsToBeReviewed": [
    {
      "requestBody": {
        "name": "<Name_of_the_Individual>"
      },
      "screeningAmlResult": {
        "statusCode": "<Status_Code>",
        "metaData": {
          "transactionId": "<Transaction_ID>",
          "requestId": "<Request_ID>"
        },
        "summary": {
          "action": "<Action_Taken>",
          "details": []
        },
        "result": {
          "hits": []
        }
      },
      "monitoringHistory": [
        {
          "monitoringTimestamp": "<Monitoring_Timestamp>",
          "statusCode": "<Status_Code>",
          "metaData": {
            "transactionId": "<Transaction_ID>",
            "requestId": "<Request_ID>"
          },
          "summary": {
            "action": "<Action_Taken>",
            "details": [
              {
                "code": "<Error_Code>",
                "message": "<Error_Message>"
              }
            ]
          },
          "result": {
            "hits": [
              {
                "name": "<Name_of_the_Hit>",
                "id": "<Hit_ID>",
                "updatedAt": "<Updated_At_Timestamp>",
                "createdAt": "<Created_At_Timestamp>",
                "aka": [],
                "sources": {
                  "adverseMedia": [],
                  "pep": [
                    {
                      "name": [
                        "<PEP_Source_Name>"
                      ],
                      "url": [
                        "<PEP_Source_URL>"
                      ],
                      "countryCodes": [
                        "<Country_Codes>"
                      ]
                    }
                  ],
                  "sanction": [],
                  "warning": [],
                  "fitnessProbity": []
                },
                "associates": [],
                "dob": [],
                "countries": [
                  "<Country>"
                ],
                "nameMatch": [
                  "<Name_Match_Detail>"
                ],
                "hitId": "<Hit_ID>",
                "details": {
                  "exactNameMatch": "<Exact_Name_Match_Boolean>",
                  "countryExists": "<Country_Exists_Boolean>"
                },
                "relevanceScore": "<Relevance_Score>"
              }
            ]
          }
        }
      ]
    }
  ]
}

Success Response Details

Parameter	Type	Description
metaData.transactionId	string	The unique transaction ID for the user
metaData.requestId	string	A computer generated unique value for each request
metaData.recordsMonitored	string	Total (cumulative) number of requests onboarded to the Monitoring DB, since the first day
metaData.needsReview	string	Original request body of the AML Screening call
recordsToBeReviewed.requestBody	string	Number of requests for which a change has been observed on the specified date
recordsToBeReviewed.screeningAmlResult	string	Response body of the original AML Screening call
recordsToBeReviewed.monitoringHistory	string	Array of all the AML responses where changes have been observed since the Original AML Screening call

Error Responses

Input Validation Error

The following is a sample response for input validation error.

{
    "message": "Input Validation Error: Date should be in YYYY-MM-DD format",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid credentials

The following is a sample response for Missing or Invalid credentials.

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Internal Server Error

The following is a sample response for a server error.

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

Error Response Details

A failure or error response from the module contains a failure status, with a relavant status code and error message. The following table lists all error responses.

Status Code	Error Message	Error Description
400	Input Validation Error	The queryDate input is invalid or not in the YYYY-MM-DD format
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
429	Rate limit error	You have exceeded the configured limit on the number of transactions permitted in a minute. Please contact the HyperVerge team for resolution
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution