Criminal Risk Verification API

This document highlights the Criminal Risk Verification API details.

API Description

Objective

The Criminal Risk Verification API takes in information such as an individual's name, date of birth, and address as its inputs, and delivers a detailed risk assessment of their potential involvement in criminal activities.

Input	Output
The details of the individual being assessed for potential criminal involvement	The details corresponding to the criminal records fetched for the individual. The complete list of output fields is available in the Success Response Details section.

info

The Criminal Risk Verification API employs fuzzy matching techniques to compare the input details against the database. The API also provides a match score, which indicates the degree of similarity between the input details and the database records.

API URL

https://ind-engine.thomas.hyperverge.co/v1/criminalRiskCheck

API Endpoint

criminalRiskCheck

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.

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)

Inputs

The following table outlines the parameters required in the API's request body:

Parameter	Description	Mandatory or Optional	Allowed Values	Default Value
name	The name of the individual	Mandatory	Not Applicable	Not Applicable
address	The residential address of the individual	Mandatory	Not Applicable	Not Applicable
fathername	The father name of the individual	Optional	Not Applicable	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/criminalRiskCheck' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "name": "<Enter_the_name>",
    "address": "<Enter_the_address>",
    "fatherName": "<Enter_the_father_name>"
}'

Success Responses

The following JSON code snippet demonstrates a success response from the API:

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "color": "<Risk_Color>",
    "numberOfCases": <Number_Of_Cases>,
    "result": [
      {
        "address": "<Address_As_Found_In_Case_Details>",
        "addressScore": <Address_Similarity_Score>,
        "algoRisk": "<Risk_Level_From_Algorithm>",
        "asrInfo": "<Additional_ASR_Info>",
        "businessCategory": "<Business_Category>",
        "caseCategory": "<Category_Of_The_Case>",
        "caseFilter": "<Applied_Case_Filter>",
        "caseNo": "<Case_Number>",
        "caseStatus": "<Status_Of_The_Case>",
        "caseTypeDescription": "<Case_Type_Description>",
        "caseTypeName": "<Case_Type_Name>",
        "caseYear": "<Year_Of_The_Case>",
        "cnr": "<CNR_Number>",
        "courtCode": <Court_Code>,
        "courtName": "<Name_Of_The_Court>",
        "decisionDate": "<Decision_Date_If_Available>",
        "distCode": <District_Code>,
        "distMatch": "<District_Match_Status>",
        "distName": "<District_Name>",
        "falconScore": <Falcon_Score>,
        "fatherMatchType": "<Father_Name_Match_Type>",
        "firNo": "<FIR_Number>",
        "firstHearingDate": "<First_Hearing_Date>",
        "isDistrict": <Is_District_Level_Case>,
        "isState": <Is_State_Level_Case>,
        "jurisdiction": <Jurisdiction_Flag>,
        "jurisdictionType": "<Jurisdiction_Type>",
        "link": "<Case_Link_URL>",
        "matchedAddress": "<Matched_Address>",
        "matchedName": "<Matched_Name>",
        "maxWordsMatched": <Maximum_Words_Matched>,
        "md5": "<MD5_Hash_Of_Case>",
        "name": "<Name_Of_The_Person>",
        "nameMatchType": "<Name_Match_Type>",
        "nameScore": <Name_Similarity_Score>,
        "natureOfDisposal": "<Nature_Of_Disposal>",
        "oparty": "<Opposing_Party>",
        "policeStation": "<Police_Station_Name>",
        "purposeOfHearing": "<Purpose_Of_Hearing>",
        "rawAddress": "<Raw_Address_From_Record>",
        "registrationDate": "<Registration_Date>",
        "score": <Overall_Case_Score>,
        "source": "<Case_Source>",
        "stateCode": <State_Code>,
        "stateMatch": "<State_Match_Status>",
        "stateName": "<State_Name>",
        "totalNameMatch": <Total_Name_Matches>,
        "type": <Case_Type_ID>,
        "underActs": "<Acts_Under_Which_Case_Is_Registered>",
        "underSections": "<Sections_Under_Which_Case_Is_Registered>",
        "uniqCaseId": "<Unique_Case_Identifier>",
        "verifycode": "<Verification_Code>",
        "wordsMatched": [
          "<Matched_Word_1>",
          "<Matched_Word_2>"
        ],
        "caseColor": "<Case_Color>"
      }
    ]
  },
  "metaData": {
    "requestId": "<Request_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code returned by the API
color	string	The risk color assigned to the individual based on the overall details and severity of all associated cases
numberOfCases	integer	The total number of cases found
address	string	The address found in the case record
addressScore	integer	The confidence score for the address match
algoRisk	string	The algorithmically derived risk level
asrInfo	string	Additional source registry information
businessCategory	string	The business category, if available
caseCategory	string	The category of the case
caseFilter	string	The filter applied for the type of case
caseNo	string	The unique case number
caseStatus	string	The current status of the case
caseTypeDescription	string	The description of the case type
caseTypeName	string	The name of the case type
caseYear	string	The year the case was registered
cnr	string	The unique case reference number
courtCode	integer	The code of the court where the case was filed
courtName	string	The name of the court handling the case
decisionDate	string	The date on which the decision was made
distCode	integer	The code of the district where the case is registered
distMatch	string	The match result for the district name
distName	string	The name of the district
falconScore	number	The score computed by the Falcon algorithm
fatherMatchType	string	The type of match found for the father's name
firNo	string	The FIR number related to the case
firstHearingDate	string	The date of the first hearing for the case
isDistrict	integer	Indicates if the jurisdiction is based on district (1 or 0)
isState	integer	Indicates if the jurisdiction is based on state (1 or 0)
jurisdiction	boolean	Specifies whether the case falls under jurisdiction
jurisdictionType	string	The level of jurisdiction such as state or district
link	string	The link to view the case document
matchedAddress	string	The address matched during verification
matchedName	string	The name matched during verification
maxWordsMatched	integer	The maximum number of words matched in the input
md5	string	The MD5 hash of the case document
name	string	The name involved in the case
nameMatchType	string	The type of name match found
nameScore	integer	The score for the name match
natureOfDisposal	string	The nature of the case disposal
oparty	string	The name of the opposing party
policeStation	string	The name of the police station associated with the case
purposeOfHearing	string	The stated purpose for the court hearing
rawAddress	string	The unprocessed address data
registrationDate	string	The date when the case was registered
score	number	The final score used to determine risk
source	string	The source from which the case was fetched
stateCode	integer	The code of the state where the case is registered
stateMatch	string	The match result for the state name
stateName	string	The name of the state
totalNameMatch	integer	The total number of words matched in the name
type	integer	The case type indicator
underActs	string	The acts under which the case is filed
underSections	string	The sections under which the case is filed
uniqCaseId	string	The unique identifier for the case
verifycode	string	The verification code for the case report
wordsMatched	array	The list of matched words from the name or address
caseColor	string	The color indicating the severity of the case
requestId	string	The unique request identifier provided in metadata

Error Responses

The following are the error responses from the API:

Missing Input - name

{
    "message": "name should not be empty",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

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

Internal 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 relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description
400	name should not be empty	The request has null or undefined value for name parameter
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution