Collections & Service Areas

Two related tools for lenders and merchants: collection zones that tell a loan-officer where a borrower is (and whether they've moved), and service areas that tell a merchant exactly where they can deliver.

Collections

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" }
    ]
  }'

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

POST /v2/collections/locate gives the officer everything they need before knocking on a door:

curl -X POST "https://api.afrihex.com/v2/collections/locate" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "loan_id": "loan_456", "customer_id": "cust_123" }'

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.

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": "drive_time",
    "center": { "lat": 5.56, "lng": -0.196 },
    "minutes": 30,
    "mode": "driving"
  }'

Supported types: drive_time, radius (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 (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.