Ecourts Search

POST /api/v1/ecourts/search

Description

The Ecourts Search API allows you to search for court case records across various Indian courts based on an individual's details. This endpoint retrieves comprehensive information about civil and criminal cases, including case status, court details, and party information. The API helps organizations perform background checks, verify litigation history, and assess legal risks associated with individuals.

Use Cases

- Pre-loan verification to identify litigation risks of potential borrowers - Background checks during customer onboarding for high-value accounts - Periodic monitoring of existing customers for new legal proceedings - Pre-employment background verification for senior positions - Vendor and contractor due diligence - Periodic checks for employees in positions of trust and responsibility - Client background research for legal professionals - Case tracking across multiple jurisdictions - Legal risk assessment for corporate clients

Technical Implementation

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

1. Obtain API Credentials: Register with Surepass to receive your API key.
2. Generate JWT Token: Use your API key to generate a JWT token.
3. Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

• Sandbox: https://sandbox.surepass.io
• Production: https://kyc-api.surepass.io

### Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: Bearer <your_token>
Content-Type	Yes	Must be set to application/json

Request Body

Parameter	Type	Required	Description
name	String	Yes	Name of the individual to search for
father_name	String	No	Father's name of the individual
source	String	No	Source of the information (e.g., "ecourt")
address	String	No	Full address of the individual
case_type	String	No	Type of case involvement (e.g., "respondent", "petitioner")
state_name	String	No	Name of the state to search within
search_type	String	Yes	Type of search (e.g., "individual")
category	String	No	Category of the case (e.g., "civil", "criminal")

Example Request

{
    "name": "Gurjeet",
    "father_name": "Jogendra",
    "source": "ecourt",
    "address": "Phatak Road, Opposite Patliputra,Nursing Home, Jharkhad",
    "case_type": "respondent",
    "state_name": "WESTBENGAL",
    "search_type": "individual",
    "category": "civil"
}

### Response Parameters

Parameter	Type	Description
data	Object	Container for the response data
data.client_id	String	Unique identifier for the client making the request
data.search_params	Object	Parameters used for the search
data.status	String	Status of the search request (e.g., "completed")
data.is_async	Boolean	Indicates if the request was processed asynchronously
data.crime_report_pdf	String	URL to PDF report if requested (empty if not requested)
data.search_result	Array	Array of case records matching the search criteria
status_code	Integer	HTTP status code of the response
success	Boolean	Indicates if the request was successful
message	String	Human-readable message about the response
message_code	String	Code representing the message type

Case Record Fields (in search_result array)

Field	Type	Description
address_state	String	State of the address
address_taluka	String	Taluka (sub-district) of the address
source	String	Source of the case information
party	String	Information about the party involved in the case
petitioner	String	Information about the petitioner in the case
respondent	String	Information about the respondent in the case
fir_year	String	Year when the FIR was filed
type	String	Type of case
address_pincode	String	Pincode of the address
state_name	String	Name of the state
under_sections	String	Sections under which the case is filed
address_wc	String	Address-related information
id	String	Unique identifier for the case record
court_name	String	Name of the court handling the case
under_acts	String	Acts under which the case is filed
address_district	String	District of the address
uniq_case_id	String	Unique identifier for the case
name_wc	String	Name-related information
case_no	String	Case number
address	String	Full address
business_category	String	Business category
time_stamp	String	Timestamp of the case record
cnr	String	CNR (Case Number Record) number
police_station	String	Police station associated with the case
case_year	String	Year when the case was filed
case_category	String	Category of the case
case_status	String	Current status of the case
address_street	String	Street address
name	String	Name of the person involved
dist_code	String	District code
fir_no	String	FIR number
state_code	String	State code
raw_address	String	Raw, unformatted address
court_code	String	Court code
md5	String	MD5 hash of the case record
oparty	String	Names of the other parties involved in the case
order_summary	String	Summary of the court order
risk_profile	String	Risk profile of the case
match_type	String	Match type for the case record
case_code	String	Code for the case

Example Successful Response

{
    "data": {
        "client_id": "ecourts_hrGBbqpYKwiJdjQjigLp",
        "search_params": {
            "name": "Gurjeet",
            "search_type": "individual",
            "pdf_report": false
        },
        "status": "completed",
        "is_async": false,
        "crime_report_pdf": "",
        "search_result": [
            {
                "address_state": null,
                "address_taluka": null,
                "source": "ecourt",
                "party": null,
                "petitioner": null,
                "respondent": null,
                "fir_year": null,
                "type": "0",
                "address_pincode": null,
                "state_name": "Punjab",
                "under_sections": "10",
                "address_wc": "6",
                "id": "260d6f1cffd441907099aff74d298d20",
                "court_name": "Civil Judge Senior Division, SAS Nagar, Mohali",
                "under_acts": "Code of Civil Procedure",
                "address_district": null,
                "uniq_case_id": "260d6f1cffd441907099aff74d298d20",
                "name_wc": "2",
                "case_no": "200400003442015",
                "address": "VPO NADALON TEHSIL GARHSHANKAR DISTT HOSHIARPUR",
                "business_category": "Civil",
                "time_stamp": null,
                "cnr": null,
                "police_station": null,
                "case_year": "2015",
                "case_category": "civil",
                "case_status": " CASE DISPOSED",
                "address_street": "vpo nadalon tehsil garhshankar distt hoshiarpur",
                "name": "GURDEEP BAGGA",
                "dist_code": "24",
                "fir_no": null,
                "state_code": "22",
                "raw_address": "      - VPO NADALON  TEHSIL  GARHSHANKAR DISTT HOSHIARPUR",
                "court_code": "2",
                "md5": "b2a8663a05a85a2f3f1be264b8fb9ccf",
                "oparty": "SATINDER KAUR, Inderjit",
                "order_summary": "The case status is disposed",
                "risk_profile": null,
                "match_type": null,
                "case_code": "200400003442015"
            },
            {
                "address_state": null,
                "address_taluka": null,
                "source": "ecourt",
                "party": null,
                "petitioner": null,
                "respondent": null,
                "fir_year": null,
                "type": "0",
                "address_pincode": null,
                "state_name": "Punjab",
                "under_sections": "25",
                "address_wc": "6",
                "id": "8001b92c99d5e339977fbbed5a62c5fc",
                "court_name": "Civil Judge Senior Division, SAS Nagar, Mohali",
                "under_acts": "Guardians and Wards Act",
                "address_district": null,
                "uniq_case_id": "8001b92c99d5e339977fbbed5a62c5fc",
                "name_wc": "2",
                "case_no": "200900000112015",
                "address": "VPO NADALON TEHSIL GARHSHANKER DISTT HOSHIARPUR",
                "business_category": null,
                "time_stamp": null,
                "cnr": null,
                "police_station": null,
                "case_year": "2015",
                "case_category": "civil",
                "case_status": " CASE DISPOSED",
                "address_street": "vpo nadalon tehsil garhshanker distt hoshiarpur",
                "name": "GURDEEP BAGGA",
                "dist_code": "24",
                "fir_no": null,
                "state_code": "22",
                "raw_address": "      - VPO NADALON TEHSIL GARHSHANKER DISTT HOSHIARPUR",
                "court_code": "2",
                "md5": "1e31c518a75ba704bd1174bdbf5c28af",
                "oparty": "Inderjit, SATINDER KAUR",
                "order_summary": "The case status is disposed",
                "risk_profile": null,
                "match_type": null,
                "case_code": "200900000112015"
            },
            {
                "address_state": null,
                "address_taluka": null,
                "source": "high court",
                "party": null,
                "petitioner": null,
                "respondent": null,
                "fir_year": "2008",
                "type": "0",
                "address_pincode": null,
                "state_name": "PUNJAB",
                "under_sections": "---",
                "address_wc": "0",
                "id": "d4ded8902af8961b862383a3dd2aedfb",
                "court_name": "High Court of Punjab and Haryana",
                "under_acts": "No Acts defined",
                "address_district": null,
                "uniq_case_id": "d4ded8902af8961b862383a3dd2aedfb",
                "name_wc": "2",
                "case_no": "208900095142013",
                "address": null,
                "business_category": null,
                "time_stamp": "2020-05-17",
                "cnr": "PHHC010618462013",
                "police_station": "MATOUR",
                "case_year": "2013",
                "case_category": null,
                "case_status": "CASE DISPOSED",
                "address_street": null,
                "name": "GURDEEP BAGGA",
                "dist_code": null,
                "fir_no": "74",
                "state_code": "22",
                "raw_address": null,
                "court_code": "1",
                "md5": "ece13a977e25210eee3384adec460441",
                "oparty": "STATE OF PUNJAB AND ORS",
                "order_summary": "The case status is disposed",
                "risk_profile": null,
                "match_type": null,
                "case_code": null
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

```json { "status_code": 401, "success": false, "message": "Invalid or expired token", "message_code": "unauthorized" } ``` This error occurs when the JWT token is missing, invalid, or expired. ```json { "status_code": 400, "success": false, "message": "Required parameters missing", "message_code": "invalid_request", "errors": { "name": "This field is required", "search_type": "This field is required" } } ``` This error occurs when required parameters are missing or invalid in the request. ```json { "data": { "client_id": "ecourts_hrGBbqpYKwiJdjQjigLp", "search_params": { "name": "NonExistentPerson", "search_type": "individual", "pdf_