Electricity Bill Details

Endpoint Overview

POST /api/v1/utility/electricity/

Description

This API endpoint retrieves detailed electricity bill information for a customer by providing their customer ID and operator code. It returns comprehensive information including customer details, billing information, and document links when available. This service enables applications to fetch real-time electricity bill data for verification, payment processing, or customer information display purposes.

Key Benefits

Instant access to customer electricity bill details without manual data entry

Verification of customer identity and billing information in real-time

Streamlined integration for utility payment applications and services

Reduced errors in billing information through direct data retrieval

Use Cases

Financial Services

Utility Payment Platforms

Government Services

Verify customer utility bills during loan application processes

Automate bill payments through banking applications

Validate address information through utility bill verification

Technical Implementation

Authentication

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

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

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 Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT format
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	Customer ID number for the electricity connection
operator_code	String	Yes	Code representing the electricity operator/provider

Example Request

{
    "id_number": "17000346322745",
    "operator_code": "MH"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for the electricity bill details
data.client_id	String	Unique identifier for the client in the system
data.customer_id	String	Customer ID number for the electricity connection
data.operator_code	String	Code representing the electricity operator/provider
data.state	String	State where the electricity connection is registered
data.full_name	String	Full name of the customer as registered with the provider
data.address	String	Complete address of the electricity connection
data.mobile	String or null	Customer's mobile number (if available)
data.user_email	String or null	Customer's email address (if available)
data.bill_amount	String	Total amount due on the electricity bill
data.bill_number	String or null	Electricity bill number (if available)
data.document_link	String or null	URL to access bill documents (if available)
status_code	Integer	HTTP status code indicating the result of the request
success	Boolean	Indicates whether the request was successful
message	String	Human-readable message describing the result
message_code	String	Code representing the result message

Example Successful Response

{
    "data": {
        "client_id": "electricity_jBxiqjAGXuymlqlbrOOb",
        "customer_id": "17000346322745",
        "operator_code": "MH",
        "state": "maharashtra",
        "full_name": "SUKHWANI",
        "address": "COLONY SOLAPUR ROAD NR LAD GIRNI SHEWALWADI 412307",
        "mobile": null,
        "user_email": null,
        "bill_amount": "1,280.00",
        "bill_number": null,
        "document_link": null
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Customer ID

Invalid Operator Code

Authentication Error

{
    "status_code": 400,
    "success": false,
    "message": "Invalid customer ID provided",
    "message_code": "invalid_customer_id"
}

This error occurs when the provided customer ID doesn't exist or is in an incorrect format.

Integration Best Practices

Security Recommendations

Store API credentials securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications to ensure data encryption

Rotate JWT tokens periodically and implement token expiration policies

User Experience Guidelines

Implement caching strategies to improve response times for frequently accessed data

Display a loading indicator while fetching electricity bill details

Format currency values appropriately for display (e.g., ₹1,280.00)

Provide clear error messages to users when bill retrieval fails

Code Samples

cURL

Python

Node.js

Related APIs

Water Bill Verification API - Retrieves water utility bill details for customers

Gas Bill Verification API - Fetches gas utility bill information

Utility Bill Payment API - Processes payments for various utility bills

Address Verification API - Verifies address information using utility bill data

Compliance and Legal Considerations

When handling electricity bill data, ensure compliance with data privacy regulations such as GDPR or local data protection laws. Customer information obtained through this API should only be used for the specific purpose disclosed to the customer. Storing this data may require additional compliance measures and customer consent. Consult with legal advisors regarding the specific requirements for your region and use case.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/utility/electricity/' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "{{ca_number}}", "operator_code": "{{operator_code}}" }'

{ "data": { "client_id": "electricity_jBxiqjAGXuymlqlbrOOb", "customer_id": "17000346322745", "operator_code": "MH", "state": "maharashtra", "full_name": "SUKHWANI", "address": "COLONY SOLAPUR ROAD NR LAD GIRNI SHEWALWADI 412307", "mobile": null, "user_email": null, "bill_amount": "1,280.00", "bill_number": null, "document_link": null }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Electricity Bill Details

Electricity Bill Details#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Electricity Bill Details

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples