Meter Management

Learn how to register, validate, and manage electricity meters in your application.

Overview

Before you can vend electricity tokens, meters must be registered in the Venshack system. This guide covers how to register new meters and manage existing ones.

Registering a Meter

Register a new meter to enable electricity vending for a property.

Request

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

{
  "meterNumber": "12345678901",
  "meterType": "PREPAID",
  "address": "Block A, Unit 5",
  "residentId": "res_abc123"
}

Parameters

Field Type Required Description
meterNumber string Yes The physical meter number (usually 11-13 digits)
meterType string Yes PREPAID or POSTPAID
address string Yes Physical address or unit identifier
residentId string No Optional resident ID to link the meter

Response

{
  "success": true,
  "data": {
    "id": "mtr_xyz789",
    "meterNumber": "12345678901",
    "meterType": "PREPAID",
    "address": "Block A, Unit 5",
    "residentId": "res_abc123",
    "status": "PENDING",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
Meter Verification
New meters are created with PENDING status. Use the validate endpoint to verify the meter exists with the electricity provider before vending.

Validating a Meter

Validate a meter number to confirm it exists with the electricity distribution company and retrieve customer details.

Request

POST /v1/meters/validate
Content-Type: application/json
Authorization: Bearer your_api_key

{
  "meterNumber": "12345678901",
  "disco": "EKEDC"
}

Supported DISCOs

Code Name Region
EKEDC Eko Electricity Distribution Company Lagos (Island, Lekki, Ajah)
IKEDC Ikeja Electric Lagos (Mainland, Ikeja)
IBEDC Ibadan Electricity Distribution Company Oyo, Ogun, Osun, Kwara
AEDC Abuja Electricity Distribution Company FCT, Niger, Kogi, Nasarawa
PHED Port Harcourt Electricity Distribution Rivers, Cross River, Akwa Ibom
KEDCO Kano Electricity Distribution Company Kano, Jigawa, Katsina

Response

{
  "success": true,
  "data": {
    "meterNumber": "12345678901",
    "customerName": "JOHN DOE",
    "address": "15 ADMIRALTY WAY, LEKKI",
    "disco": "EKEDC",
    "meterType": "PREPAID",
    "tariffClass": "R2",
    "isValid": true
  }
}
Validation is Free
Meter validation does not incur any charges. You can validate meters as often as needed to confirm customer details before vending.

Listing Meters

Retrieve all meters registered for your estate or organization.

Request

GET /v1/meters?page=1&limit=20&status=ACTIVE
Authorization: Bearer your_api_key

Query Parameters

Parameter Type Default Description
page integer 1 Page number for pagination
limit integer 20 Number of results per page (max 100)
status string - Filter by status: ACTIVE, PENDING, INACTIVE
search string - Search by meter number or address

Response

{
  "success": true,
  "data": {
    "meters": [
      {
        "id": "mtr_xyz789",
        "meterNumber": "12345678901",
        "meterType": "PREPAID",
        "address": "Block A, Unit 5",
        "status": "ACTIVE",
        "lastVend": "2024-01-14T15:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

Best Practices

1. Always Validate Before First Vend

Before vending to a meter for the first time, always validate it to ensure the meter number is correct and retrieve customer details for verification.

2. Store Meter IDs

After registering a meter, store the returned id in your database. Use this ID for all subsequent operations instead of the meter number.

3. Handle Multiple Meters Per Unit

Some properties may have multiple meters (e.g., main power and backup generator). Use the address field to differentiate them clearly.

Next Steps