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

FieldTypeRequiredDescription
providerstringYesCode of the electricity board, 2 to 40 letters, digits or underscores, for example MAHAVITRAN. Case and spaces are ignored.
consumer_numberstringYesConsumer number printed on the bill, 3 to 30 letters, digits or slashes.
installation_numberstringNoInstallation number printed on the bill, 1 to 30 letters, digits or slashes; needed by some boards.
mobilestringNoMobile 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

FieldTypeDescription
namestringName on the connection.
addressstringAddress of the connection.
split_addressobjectThe connection address broken into parts.
split_address.districtarrayDistrict name, as a list.
split_address.statearrayState name, as a list.
split_address.cityarrayCity name, as a list.
split_address.pincodestringSix-digit pincode.
split_address.countryarrayCountry name, as a list.
split_address.address_linestringStreet-level part of the address.
consumer_nostringConsumer number.
account_idstringAccount ID, where the board uses one.
electricity_providerstringThe electricity board.
emailstringEmail address on the connection, when recorded.
mobile_numberstringMobile number on the connection, when recorded.
tariff_codestringTariff category of the connection.
section_namestringSection or sub-division office.
billing_unitstringBilling unit of the connection.
consumption_unitsstringUnits consumed in the latest bill.
bill_nostringNumber of the latest bill.
bill_datestringDate of the latest bill.
bill_issue_datestringDate the latest bill was issued.
bill_due_datestringDate the latest bill is due.
bill_amountstringAmount of the latest bill.
amount_payablestringAmount payable now.
due_amountstringAmount 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.