Criminal Risk Check API

This document highlights the Criminal Risk Check API details.

API Description

Objective

The Criminal Risk Check (CRC) 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 Check API employs fuzzy matching techniques to compare the input details against the database. the Criminal Risk Check 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 Criminal Risk Check 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 Criminal Risk Check 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 Criminal Risk Check API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
name	Mandatory	string	The full name of the individual	Not Applicable	Not Applicable
address	Mandatory	string	The residential address of the individual	Not Applicable	Not Applicable
fatherName	Mandatory	string	The father's name of the individual. Improves match accuracy when address confidence is low or unavailable	Not Applicable	Not Applicable
dob	Optional	string	The date of birth of the individual. Used as an additional filter when provided	DD/MM/YYYY	Not Applicable
jurisdictionType	Optional	string	By default, case searches are limited to the district derived from the individual's address. Use this parameter to expand the search to the individual's state or across India.	panIndia or state	Not Applicable
enablePDF	Optional	string	Set to yes to include a formatted PDF report in the response. Includes a visual risk gauge, personal details, and a card for each matched case Useful for audit and record-keeping purposes See a sample report	yes or no	Not Applicable

Request

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

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/criminalRiskCheck' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
    "name": "<Enter_the_name>",
    "address": "<Enter_the_address>",
    "fatherName": "<Enter_the_father_name>",
    "dob": "<Enter_the_date_of_birth>",
    "jurisdictionType": "<Enter_the_jurisdiction_type>",
    "enablePDF": "<yes_or_no>"
}'

Success Responses

The following JSON code snippet demonstrates a success response from the Criminal Risk Check 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>"
      }
    ],
    "pdf": "<PDF_Base64_Encoded_String>"
  },
  "metaData": {
    "requestId": "<Request_ID>"
  }
}

Success Response Details

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

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The HTTP status code returned by the Criminal Risk Check API
color	string	The overall risk color assigned to the individual based on the severity of all associated cases. See Risk Color Levels for all possible values
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, calculated using structural matching across locality, street, and city. A higher score indicates a stronger address match
algoRisk	string	The risk level derived for the specific case based on the legal sections and acts involved. Each act and section is mapped to a severity category based on client-defined requirements. For example, average risk
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 strategy used to match the father's name against the database record. Uses the same match types as nameMatchType
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 strategy used to match the input name against the database record. Possible values: EXACT_MATCH : Both names are identical (e.g., "Rahul Sharma" = "Rahul Sharma") EXACT_FUZZY_MATCH : Minor phonetic variations (e.g., "Rahul Sharma" ≈ "Rahool Sharma") PARTIAL_EXACT_MATCH : One name fully matches a part of the other (e.g., "Rahul Kumar Sharma" = "Rahul Sharma") PARTIAL_FUZZY_MATCH : Partial match with slight variations (e.g., "Rahul Kumar Sharma" ≈ "Rahool Sharma") NO_MATCH : Names do not match
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 risk color for this specific case. See Risk Color Levels for all possible values
pdf	string	The base64-encoded PDF report containing a visual risk gauge, personal details, and a detailed card for each matched case. Useful for audit purposes. Returned only when enablePDF is set to yes. See a sample report. Disclaimer: This report is compiled from publicly available records across courts, tribunals, and defaulters lists in India. Its accuracy depends on publicly available data at the time of retrieval. It should not be construed as legal, financial, or professional advice. Users are advised to conduct independent verification before making decisions based on this report.
requestId	string	The unique request identifier provided in metadata

Risk Color Levels

The following table describes the possible values for the color and caseColor fields:

Color	Risk Level	Description
Red	High / Very High Risk	One or more cases with high or very high risk severity are associated with the individual
Yellow	Requires Manual Review	The legal section or act associated with the case is not yet categorized in the risk database. Manual review is recommended
Green	Low / Very Low Risk	No significant criminal risk detected; any associated cases are of low severity

Error Responses

The following are the error responses from the Criminal Risk Check API:

Missing Input - name

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

Invalid Jurisdiction

{
    "message": "Input Validation Error: is not one of enum values: panIndia,state",
    "statusCode": 400,
    "status": "failure"
}

Invalid enablePDF Value

{
    "message": "Input Validation Error: is not one of enum values: yes,no",
    "statusCode": 400,
    "status": "failure"
}

Missing/Invalid Credentials

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

Internal Server Error

{
    "status": "failure",
    "statusCode": 500,
    "message": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

External Source Downtime

{
    "message": "External source downtime",
    "error": "EXTERNAL_DOWNTIME",
    "statusCode": 503,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Timeout

{
    "message": "timeout error",
    "statusCode": 504,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

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	Error Resolution
400	name should not be empty	The request has a null or undefined value for the name parameter	Ensure the name field is present and non-empty in the request body
400	Input Validation Error: is not one of enum values: panIndia,state	An invalid value was passed for jurisdictionType	Use panIndia or state as the value for jurisdictionType
400	Input Validation Error: is not one of enum values: yes,no	An invalid value was passed for enablePDF	Use yes or no as the value for enablePDF
401	Missing/Invalid credentials	The request is missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid credentials from the dashboard's credentials tab
500	Internal Server Error	An unexpected error occurred on the server	Check the request headers or contact the HyperVerge team for resolution
503	External source downtime	The underlying data source is temporarily unavailable	Retry the request after some time. Contact the HyperVerge team if the issue persists
504	timeout error	The request timed out before a response was received	Retry the request after some time. Contact the HyperVerge team if the issue persists