Skip to main content

Partner Locator

A consumer "find my partner" feature built on the same location primitives as Location Monitoring, for a different audience: an end user sharing their own location with one person they trust — a partner, a parent, a driver — not an institution tracking a customer under legal consent.

:::note Why not one shared ID? The obvious design is a single static ID you hand out like a password. It doesn't hold up: if you've shared it with three people, you can't revoke just one of them without regenerating the ID and re-sharing with the other two. Partner Locator instead mints a short-lived, single-use share token that redeems into a pairing tied to the recipient's own account — so every person you've shared with can be revoked individually, with zero effect on anyone else. :::

Share your location​

POST /v2/locator/share-token mints a token good for 15 minutes and one redemption. Send it to the one person you want to share with — over WhatsApp, SMS, whatever channel you'd already use.

curl -X POST "https://api.afrihex.com/v2/locator/share-token" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "My partner", "share_duration_hours": 24 }'
{
  "success": true,
  "data": {
    "token": "28e46e92bdf8ed913feca163a1519fb",
    "expires_at": "2026-09-11T18:15:00Z"
  }
}

label is just how this person shows up in your own "who can see me" list. share_duration_hours bounds how long the resulting pairing stays active once redeemed — omit it for permanent-until-you-revoke, or cap it (max 720 hours / 30 days) for a time-boxed share.

Redeem a code​

The recipient calls POST /v2/locator/redeem with the token, under their own account. This is what actually creates the pairing:

curl -X POST "https://api.afrihex.com/v2/locator/redeem" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "token": "28e46e92bdf8ed913feca163a1519fb" }'
{
  "success": true,
  "data": {
    "pairing_id": "9f1c2e7a4b3d4f0a8c6e1d2b3a4f5e6d",
    "label": "My partner",
    "status": "active",
    "target_id": 42,
    "target_name": "Ama"
  }
}

target_id/target_name tell the redeemer whose location they just gained access to — save target_id, it's what you pass to GET /v2/locator/{targetId}/location. A token that's unknown, expired, already used, or is your own comes back 400.

Who can see you, and who you can see​

Two mirrored list endpoints:

# Everyone who can currently see YOUR location
curl "https://api.afrihex.com/v2/locator/viewers" -H "X-API-Key: $AFRIHEX_API_KEY"

# Everyone YOU can currently see
curl "https://api.afrihex.com/v2/locator/watching" -H "X-API-Key: $AFRIHEX_API_KEY"

viewers is your revoke list — each entry's pairing_id is what you pass to DELETE /v2/locator/viewers/{pairingId}. watching is how a client discovers which target_ids it's allowed to query — it comes back with target_name/target_email so you're not stuck rendering a list of raw account numbers.

Revoke one person​

curl -X DELETE "https://api.afrihex.com/v2/locator/viewers/9f1c2e7a4b3d4f0a8c6e1d2b3a4f5e6d" \
  -H "X-API-Key: $AFRIHEX_API_KEY"

Deactivates that one pairing immediately. Everyone else you've shared with — untouched.

Report your location​

POST /v2/locator/checkin updates your own last-known location. Call it on every app open/login (any device), and periodically in the background while sharing is on:

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

Identity here is the account, not the physical device — if a phone is lost or dead, logging into AfriHex from any other phone reports a fresh location right away, so whoever you've shared with can find you without needing your specific device back.

Get a location​

curl "https://api.afrihex.com/v2/locator/42/location" -H "X-API-Key: $AFRIHEX_API_KEY"
{
  "success": true,
  "data": {
    "lat": 5.6037,
    "lng": -0.1870,
    "accuracy_m": 12.5,
    "source": "checkin",
    "recorded_at": "2026-09-11T18:10:00Z"
  }
}

You can always fetch your own location for free. For anyone else, you need an active pairing — otherwise this 404s, and deliberately the same 404 whether there's no pairing or the target just hasn't reported a location yet, so this endpoint can't be used to probe who has granted you access.

API reference​

See Partner Locator — API Reference for every endpoint in this group.