Skip to main content

Understanding Confidence and Verification

The business problem​

AfriHex responses carry several fields that all sound like "how much can I trust this," but they measure genuinely different things, and mixing them up is how a bank ends up treating a database match as if a human confirmed it in person. This guide separates five distinct claims so you read the right field for the decision you're actually making:

You're askingNot the same as
Does this address exist in the registry at all? (existence)Is it this specific customer's address?
Was this matched against a third-party database? (source match)Was it confirmed by anyone on the ground?
Did the customer themselves enter or confirm this? (user confirmation)Is it true?
Did a field agent or a real event confirm it? (field verification)Is it the customer's current address, not a past one?
Was a delivery confirmed at this location? (delivery confirmation)Was it confirmed to the right person?

What AfriHex returns​

Every one of these is a real field somewhere in the API, not a single unified "trust score":

ConceptFieldEndpointWhat it actually measures
Existence404 NOT_FOUND vs. 200GET /v2/lookup, GET /v2/reverse, GET /v2/hexcode/{code}Whether the identifier resolves at all — a precondition, not a confidence score
Data completenessquality_score (0.0–1.0), quality_tier (high/medium/low)Most geocoding endpointsHow complete the record is (street, area, postcode, coordinates) — not independent verification
Source matchprovenance.source: "third_party_match"GET /v2/lookup, GET /v2/reverseMatched against an external registry (GhanaPostGPS) — never confirmed on the ground for these two endpoints
User confirmationprovenance.source: "user_confirmed"Wherever a customer explicitly enters/confirms their own locationThe address owner said so — doesn't mean it's accurate
Field/agent verificationprovenance.source: "agent_verified"A field agent's manual structure-point promotion, or a signed proof-of-deliveryIndependently confirmed by a human or a real event — the strongest provenance tier
Live proximity matchresult: "NEAR"/"FAR", confidencePOST /v2/verify/proximityA declared address vs. a live device GPS fix, right now — see caveats below
Delivery confirmationlocation_verified, recipient_verified, delivery.confirmed webhookPOST /v2/pod/confirmA handover happened near the destination — see below

Before you begin​

  • Know which endpoint produced the field you're reading — the same word (confidence, verified) means different things on different endpoints. This guide exists because those names collide.
  • Decide your own policy thresholds before you see live data — see Identity & KYC's quality-score bands for a starting point, but the numbers are yours to set.

Copyable request​

The clearest side-by-side comes from proximity verification, since it returns several of these axes in one response:

curl -X POST "https://api.afrihex.com/v2/verify/proximity" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "consent_token": "tok_...",
    "declared_address": "GA-142-7281",
    "device_location": { "lat": 5.5561, "lng": -0.1962, "gps_accuracy_m": 12, "is_mock_location": false }
  }'

Full example response​

{
  "success": true,
  "data": {
    "verification_id": "6f3c…",
    "result": "NEAR",
    "verified": true,
    "confidence": 0.97,
    "proximity": { "distance_m": 18.4, "within_threshold": true },
    "integrity": {
      "mock_location": "NOT_DETECTED",
      "gps_accuracy": "GOOD",
      "provider": "gps",
      "ip_geo_match": "MATCH"
    },
    "timestamp": "2026-08-05T15:30:00Z"
  }
}

Field-by-field explanation​

  • result — a spatial fact: was the device physically near the declared address, right now. It says nothing about whose device it was.
  • verified — a derived boolean (NEAR and confidence ≥ 0.6); it's a decision AfriHex made for you, not a separate independent check.
  • confidence — how much AfriHex trusts this specific reading (GPS accuracy, mock-location signals, IP-geo agreement) — not how much you should trust the customer.
  • integrity.mock_location — a spoofing signal, NOT_DETECTED is the absence of evidence of spoofing, not proof the location is genuine.

What none of this proves​

Every field above is location evidence — a signal about where a device or a record sits — not guaranteed proof of identity, ownership, residence, creditworthiness, or legality. A verified: true proximity match means a phone was physically near a declared address at one moment; it does not by itself establish that the phone's holder is who they claim to be, that they own or reside at that address, that they're creditworthy, or that anything about the transaction is lawful. Treat every result here as one input to a decision your own policies make — not the decision itself. See Identity & KYC's compliance notes for how this plays out in a lending flow, and Using Risk Scores Responsibly for the same caveat applied to fraud and AML signals.

Error and edge cases​

  • High quality_score with source: third_party_match. A complete registry record is not the same as ground-truth confirmation — a well-documented address can still be the wrong customer's. See Choose the Right Location Identifier.
  • verified: false with result: NEAR. Possible when confidence < 0.6 despite proximity — a low-accuracy GPS fix can be spatially close and still untrusted. Read confidence and integrity together, not result alone.
  • Integrity fields reporting NOT_PROVIDED. The device didn't send accuracy/mock-location data — treat as unknown, not as a pass.
  • A signed certificate with signature_valid: true. Proves the certificate itself wasn't tampered with after issuance — it does not mean the underlying verification is still current; check revoked and issued_at too. See Signed certificates.
  • Proof of delivery's recipient_verified. Confirms someone accepted the delivery near the destination — not that they were the named customer, unless your delivery partner independently checked ID.

Production checklist​

  • Never display or store a single "trust score" that blends quality_score, provenance.confidence, and proximity confidence — keep them as separate fields with separate meanings.
  • Set your own verified/threshold policy in writing before launch — the defaults (quality_score ≥ 0.8, proximity confidence ≥ 0.6) are starting points, not regulatory requirements.
  • Log which endpoint and provenance.source backed every decision you make off a location — you'll need this for audits and disputes.
  • Route anything below your threshold to human review instead of a silent auto-reject or auto-approve.

Related endpoints / next guide​