Address Verification API

Verify a claimed Nigerian house address against the address registered to a prepaid electricity meter across supported Nigerian DISCOs.

Standalone verification product

This API is independent of Venshack estates, vending, and meter management. The meter does not need to be registered in Venshack, and the request does not create a Venshack meter or purchase electricity.

Use Cases

Proof-of-address checks for lending and financial services
KYC and customer onboarding
Address confirmation for compliance and risk reviews
Comparing a customer-provided address with utility-provider records

Endpoint

POST /v1/address/verify
Authorization: Bearer your_api_key
Content-Type: application/json

{
  "meter_number": "04231221345",
  "address": "24 Sandbox Avenue, Victoria Island, Lagos",
  "disco_code": "EKO"
}

disco_code accepts a supported DISCO code or a Nigerian state name. State names are resolved to the serving DISCOs automatically.

Supported DISCO Codes

ABUJA, BENIN, EKO, IKEJA, IBADAN, ENUGU, PH, JOS, KADUNA, KANO, and YOLA.

How This Differs from the Meters API

Address Verification API	Meters API
Standalone proof-of-address checks	Manages meters owned by your Venshack organization
Works across supported Nigerian DISCOs	Uses Venshack meter inventory and approval workflows
No estate or registered Venshack meter required	Creates, imports, lists, validates, and deletes Venshack meters
Returns registered address, owner, and confidence score	Returns meter-management and organization data

Response

{
  "success": true,
  "data": {
    "verified": true,
    "confidence_level": 66,
    "house_address": "24 SANDBOX AVENUE VICTORIA ISLAND LAGOS",
    "house_owner": "SANDBOX CUSTOMER",
    "disco_code": "EKO"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-08-08T10:30:00.000Z"
  }
}

Interpreting Results

verified is true when the confidence level is at least 50.
confidence_level is a 0-100 address similarity score.
A completed non-match still returns HTTP 200 with verified: false.

Pricing

₦200 per live verification. Failed provider lookups are refunded.

Sandbox Test Cases

TEST API keys use deterministic responses and never call the live address provider. Choose the meter number for the outcome you want to test. The claimed address may be any non-empty string.

Meter number	Scenario	Verified	Confidence
`1111111111111`	Exact match	`true`	100
`2222222222222`	Close match	`true`	66
`3333333333333`	No match	`false`	0
`0000000000000`	Provider / lookup failure	HTTP 400 error

Any other meter number returns an error asking you to use a documented sandbox meter. Sandbox requests are free but still appear in API call logs. They do not write live address-verification records, populate KV, or emit address.verified webhooks.

Webhook

Subscribe to address.verified to receive completed verification results. See the Webhooks Guide.