API reference / KYC / Identity
Electricity bill (proof of address)
Consumer name, address and latest bill from the electricity board. provider is the board code, e.g. MAHAVITRAN; installation_number and mobile are optional.
POST
/v1/verify/electricity-bill- Authentication
- Bearer token
- Scope
kyc:verify
Before you integrate
- Only some boards are supported; an unsupported provider code is rejected and the call is refunded.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | Code of the electricity board, 2 to 40 letters, digits or underscores, for example MAHAVITRAN. Case and spaces are ignored. |
consumer_number | string | Yes | Consumer number printed on the bill, 3 to 30 letters, digits or slashes. |
installation_number | string | No | Installation number printed on the bill, 1 to 30 letters, digits or slashes; needed by some boards. |
mobile | string | No | Mobile number registered with the board. 10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored. |
Sample code
Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.
curl -sS -X POST 'https://grappi.ai/v1/verify/electricity-bill' \
-H "Authorization: Bearer $GRAPPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "MAHAVITRAN",
"consumer_number": "123456789012"
}'Sample response
{
"request_id": "req_01HZY3K8M2",
"result": {
"name": "ASHA RAO",
"address": "12 Example Lane, Pune, Maharashtra, 411001",
"split_address": {
"district": [
"Pune"
],
"state": [
"Maharashtra"
],
"city": [
"Pune"
],
"pincode": "411001",
"country": [
"India"
],
"address_line": "12 Example Lane"
},
"consumer_no": "123456789012",
"electricity_provider": "MAHAVITRAN",
"tariff_code": "LT-I",
"consumption_units": "182",
"bill_no": "BL2026100123",
"bill_date": "2026-10-05",
"bill_due_date": "2026-10-20",
"bill_amount": "1480.00",
"amount_payable": "1480.00",
"due_amount": "0.00"
}
}Response fields
| Field | Type | Description |
|---|---|---|
name | string | Name on the connection. |
address | string | Address of the connection. |
split_address | object | The connection address broken into parts. |
split_address.district | array | District name, as a list. |
split_address.state | array | State name, as a list. |
split_address.city | array | City name, as a list. |
split_address.pincode | string | Six-digit pincode. |
split_address.country | array | Country name, as a list. |
split_address.address_line | string | Street-level part of the address. |
consumer_no | string | Consumer number. |
account_id | string | Account ID, where the board uses one. |
electricity_provider | string | The electricity board. |
email | string | Email address on the connection, when recorded. |
mobile_number | string | Mobile number on the connection, when recorded. |
tariff_code | string | Tariff category of the connection. |
section_name | string | Section or sub-division office. |
billing_unit | string | Billing unit of the connection. |
consumption_units | string | Units consumed in the latest bill. |
bill_no | string | Number of the latest bill. |
bill_date | string | Date of the latest bill. |
bill_issue_date | string | Date the latest bill was issued. |
bill_due_date | string | Date the latest bill is due. |
bill_amount | string | Amount of the latest bill. |
amount_payable | string | Amount payable now. |
due_amount | string | Amount overdue. |
Errors
Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.