eFIR Verification API

This document highlights the eFIR Verification API details.

API Description

Objective

The eFIR Verification API provides information about a filed eFIR (electronic First Information Report), including details such as the father name of the complainant, address, and related case information.

Input	Output
The details of the complainant	The details corresponding to the eFIR. The complete list of output fields is available in the Success Response Details section.

API URL

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

API Endpoint

eFIRCheck

Overview

The API is RESTful, utilizing standard HTTP verbs and status codes. Responses are provided in JSON format, and all images and files must be uploaded as form-data via a POST request.

Authentication

To access the API, you must obtain a unique pair of application ID (appId) and application key (appKey) from HyperVerge for identity verification.

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 complainant journey	This should be both unique and easily associated with the complainant'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 complainant as recorded in the filed eFIR	Mandatory	Not Applicable	Not Applicable
fatherName	The name of the complainant's father	Optional	Not Applicable	Not Applicable
address	The full address of the complainant	Optional	Not Applicable	Not Applicable
source	The filed eFIR	Mandatory	"fir"	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/eFIRCheck' \
--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>",
    "fatherName": "<Enter_the_fatherName>",
    "address": "<Enter_the_address>",
    "source": "<Enter_the_source>"
}'

Success Response

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

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "cases": [
            {
                "address": "<Address_Of_The_Case>",
                "addressDistrict": "<District_Of_The_Case>",
                "addressMatch": "<Address_Match_Status>",
                "addressPincode": "<Pincode_Of_The_Case>",
                "addressRerankScore": "<Address_Rerank_Score>",
                "addressState": "<State_Of_The_Case>",
                "addressStreet": "<Street_Of_The_Case>",
                "addressTaluka": "<Taluka_Of_The_Case>",
                "addressWc": "<Word_Count_Of_Address>",
                "algo": "<Algorithm_Name>",
                "algoRisk": "<Algorithm_Risk_Level>",
                "allCandidates": [
                    "<Candidate_1>",
                    "<Candidate_2>",
                    "<Candidate_3>",
                    "<Candidate_4>",
                    "<Candidate_5>",
                    "<Candidate_6>"
                ],
                "asrInfo": "<Act_Section_Related_Info>",
                "bullzaiOnly": "<Bullzai_Only_Status>",
                "caseCategory": "<Category_Of_The_Case>",
                "cleanName": "<Cleaned_Name_Of_Person>",
                "date": "<Date_Of_Case>",
                "decidingFactor": "<Deciding_Factor>",
                "distMatch": "<District_Match_Status>",
                "distName": "<District_Name>",
                "doorMatch": "<Door_Match_Status>",
                "fatherMatchType": "<Father_Name_Match_Type>",
                "fatherName": "<Father_Name>",
                "fatherNameMatch": "<Father_Name_Match_Status>",
                "firNo": "<FIR_Number>",
                "firYear": "<FIR_Year>",
                "jinaAddressRank": "<Jina_Address_Rank>",
                "jinaNameRank": "<Jina_Name_Rank>",
                "jurisdiction": "<Jurisdiction_Status>",
                "jurisdictionType": "<Jurisdiction_Type>",
                "link": "<Case_Link>",
                "md5": "<MD5_Hash>",
                "name": "<Name_Of_Person>",
                "nameMatch": "<Name_Match_Status>",
                "nameMatchType": "<Name_Match_Type>",
                "nameRerankScore": "<Name_Rerank_Score>",
                "nameWc": "<Name_Word_Count>",
                "oparty": "<Opposite_Party_Name>",
                "overallMatch": "<Overall_Match_Status>",
                "policeStation": "<Police_Station_Name>",
                "rawAddress": "<Raw_Address_Of_Case>",
                "ref": "<Reference_ID>",
                "source": "<Source_Of_Info>",
                "stateMatch": "<State_Match_Status>",
                "stateName": "<State_Name>",
                "timeStamp": "<Timestamp>",
                "type": "<Case_Type>",
                "underActs": "<Acts_Involved>",
                "underSections": "<Sections_Involved>",
                "uniqCaseId": "<Unique_Case_ID>",
                "villageMatch": "<Village_Match_Status>",
                "year": "<Year_Of_Case>"
            }
        ],
        "flexiSearchId": "<Flexi_Search_ID>",
        "flexiSourceId": "<Flexi_Source_ID>",
        "groupBy": {},
        "message": "<Processing_Message>",
        "numresults": "<Number_Of_Results>",
        "status": "<Status_Of_Processing>"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

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

Parameter	Type	Description
address	string	The complete address related to the case
addressDistrict	string	The district of the address
addressMatch	boolean	Indicates if the address matches
addressPincode	string	The postal code for the address
addressRerankScore	number	A score indicating the relevance of the address match
addressState	string	The state in which the address is located
addressStreet	string	A cleaned-up version of the street address
addressTaluka	string	The taluka (sub-district) of the address
addressWc	integer	The word count of the address
algo	string	The algorithm used for the match
algoRisk	string	The risk level associated with the case
allCandidates	array	A list of names of individuals related to the case
asrInfo	string	The legal information pertaining to the case
bullzaiOnly	boolean	Indicates if the case is based solely on the bullzai algorithm
caseCategory	string	The category of the case
cleanName	string	The cleaned name of the individual involved
date	string	The date associated with the case
decidingFactor	string	The main factor for case matching
distMatch	boolean	Indicates if the district matches
distName	string	The name of the district
doorMatch	boolean	Indicates if the door number matches
fatherMatchType	string	The matching status of the father's name
fatherName	string	The name of the victim's father
fatherNameMatch	boolean	Indicates if the father's name matches
firNo	string	The FIR (First Information Report) number associated with the case
firYear	integer	The year of the FIR
jinaAddressRank	integer	The rank of the address match
jinaNameRank	integer	The rank of the name match
jurisdiction	boolean	Indicates if the case falls under any specific jurisdiction
jurisdictionTypea	string	The type of jurisdiction
link	string	A link to additional information related to the case
md5	string	The MD5 hash of the case information for integrity verification
name	string	The name of the individual involved in the case
nameMatch	boolean	Indicates if the name matches
nameMatchType	string	The type of name match
nameRerankScore	number	A score indicating the relevance of the name match
nameWc	integer	The word count of the name
oparty	string	The opposing party's name related to the case
overallMatch	boolean	The overall matching status of the case
policeStation	string	The police station associated with the case
rawAddress	string	The unprocessed address string
ref	string	A reference ID associated with the case
source	string	The source from which the case information is derived
stateMatch	boolean	Indicates if the state matches
stateName	string	The name of the state
timeStamp	string	The timestamp of when the case information was recorded
type	integer	A numeric representation of the case type
underActs	string	The legal acts under which the case falls
underSections	string	The sections of the law relevant to the case
uniqCaseId	string	A unique identifier for the case
villageMatch	boolean	Indicates if the village matches
year	integer	The year associated with the case
flexiSearchId	string	A unique identifier for the flexi search operation
flexiSourceId	string	A unique identifier for the source of the data
groupBy	object	An object for grouping results
message	string	A status message indicating that processing is complete
numresults	integer	The count of results found
status	integer	A numeric status code indicating the state of processing

Error Responses

The following are the error responses from the API:

Missing Input - Name

{
    "message": "Invalid name",
    "statusCode": 400,
    "status": "failure",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing Input - Source

{
    "message": "source 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"
}

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	Invalid name	This error occurs when a name field is empty or invalid
400	source should not be empty	This error occurs when a source field is empty
400	Input Validation Error: Headers: requires property "transactionid"	This error occurs when the transactionid field is missing in the request headers
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values
503	External Downtime	Please contact the HyperVerge team for resolution