Collections & Service Areas

Part of AfriHex Operate — two related tools for lenders and merchants: collection zones that tell a loan-officer where a borrower is (and whether they've moved, the same banking flow described in AfriHex Verify), and service areas that tell a merchant exactly where they can deliver.

Collections

Every endpoint in this section requires Banking Suite access — it's provisioned per institution, not implied by holding an API key. An ungranted account gets 403 BANKING_ACCESS_REQUIRED.

Register zones for a loan

POST /v2/collections/register attaches the borrower's known zones (home, work) to a loan, keyed by hex code:

curl -X POST "https://api.afrihex.com/v2/collections/register" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loan_id": "loan_456",
    "customer_id": "cust_123",
    "consent_token": "tok_...",
    "registered_zones": [
      { "type": "home", "hex_code": "AF-GH-7-0GXTQD5RFZZZZ", "label": "Apartment" },
      { "type": "work", "hex_code": "AF-GH-7-0GXTQD5RJ0000", "label": "Office" }
    ]
  }'

{
  "success": true,
  "data": {
    "loan_id": "loan_456",
    "customer_id": "cust_123",
    "registered": 2
  }
}

Register zones in bulk with POST /v2/collections/bulk-register (up to 1,000).

Request object — POST /v2/collections/register:

Parameter	Type	Required	Definition
loan_id	string	required	The loan
customer_id	string	required	The customer
consent_token	string	required	The consent token
registered_zones	array<object>	required	Zones the borrower occupies

Each registered_zones item: { "type": "home" \| "work", "hex_code": string, "label": string }.

Locate a borrower before a visit

GET /v2/collections/locate?loan_id= gives the officer everything they need before knocking on a door:

curl "https://api.afrihex.com/v2/collections/locate?loan_id=loan_456" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

{
  "success": true,
  "data": {
    "loan_id": "loan_456",
    "customer_id": "cust_123",
    "consent_status": "active",
    "registered_zones": [
      {
        "type": "home",
        "hex_code": "AF-GH-7-0GXTQD5RFZZZZ",
        "label": "Apartment",
        "last_seen": "2026-08-04T08:00:00Z",
        "frequency": "daily",
        "confidence": "high"
      }
    ],
    "address_stable": true,
    "moved_flag": false
  }
}

The response reports whether the customer's address is stable or they've moved from their registered zones, the last verified location, and an optimised collection route. Combined with Monitoring, it turns "the customer isn't answering" into a precise, consented next step.

Your own access history

GET /v2/banking/audit-log returns your own account's Banking Suite access trail (who called what, when, from where) — useful for pointing a compliance reviewer at, without asking us for it. See Identity & KYC — Compliance notes.

Service areas

Merchants can define where they deliver — as a drive-time polygon, a radius, or a custom polygon — and check any coordinate against it instantly.

Create a service area

POST /v2/service-area

curl -X POST "https://api.afrihex.com/v2/service-area" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Accra Central — 30 min",
    "type": "isochrone",
    "center": { "lat": 5.56, "lng": -0.196 },
    "minutes": 30,
    "mode": "driving"
  }'

{
  "success": true,
  "data": {
    "id": "sa_21",
    "name": "Accra Central — 30 min",
    "type": "isochrone",
    "resolution": 9,
    "cell_count": 320,
    "center": { "lat": 5.56, "lng": -0.196 },
    "created_at": "2026-07-20T12:00:00Z"
  }
}

Supported types: isochrone (drive/walk/cycle-time contour), circle (center + radius_km), and polygon.

Request object — POST /v2/service-area:

Parameter	Type	Required	Definition
name	string	required	Display name for the area
type	string	required	isochrone, circle, or polygon
center	object	for isochrone/circle	{ lat, lng } origin
minutes	number	for isochrone	Drive-time contour in minutes
mode	string	optional	driving, foot, bicycle, or motor_scooter (default driving)
radius_km	number	for circle	Circle radius
polygon	array	for polygon	Exterior ring as [lng, lat] pairs
resolution	integer	optional	H3 cover resolution (6–10, default 9)

Exactly the fields for the chosen type are required.

Check a point

POST /v2/service-area/check answers "can we deliver here?" in one call:

curl -X POST "https://api.afrihex.com/v2/service-area/check" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lat": 5.6037, "lng": -0.1870 }'

{
  "success": true,
  "data": { "in_area": true, "areas": ["Accra Central — 30 min"] }
}

Batch-check many points with POST /v2/service-area/bulk-check. List, inspect, and delete service areas with GET /v2/service-area, GET /v2/service-area/{id}, and DELETE /v2/service-area/{id}.

API reference

See Collections & Service Areas — API Reference for every endpoint in this group.