Skip to main content

Validate a Customer Address for Onboarding

The business problem​

An onboarding flow needs a decision — accept, escalate to manual review, or reject — from whatever address evidence a new customer provides. The temptation is to treat a passing address check as "this customer is who and where they say they are." It isn't. This guide walks the actual decision AfriHex can support, and draws the line explicitly at what it can't.

What an address match can establish: that a claimed address exists, how complete its data is, and — with a live device fix — that a device was physically near it at one moment.

What it cannot establish, on its own: that the customer owns or resides at that address, that they are who they claim to be, or that they have permission to use it (a shared compound, a relative's house, a forwarding address). Ownership, residence, identity, and permission are claims about a person; AfriHex's evidence is about a location.

What AfriHex returns​

curl -X POST "https://api.afrihex.com/v2/kyc/verify" \
  -H "X-API-Key: $AFRIHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_123",
    "method": "gps_code",
    "location": { "gps_code": "GA-142-7281" },
    "consent_token": "tok_..."
  }'

Before you begin​

  • A consent_token — address verification for onboarding requires the customer's consent, same as monitoring (see Location Monitoring — Grant consent).
  • Decide your method based on what evidence you actually have — see the table below. Don't default to manual because it's the easiest to send; it's also the lowest-trust input.
  • Set your accept/escalate/reject thresholds before you see live data — see Production checklist.
methodWhen to use itRelative trust
gps_fixLive GPS from the customer's device, captured in-appHighest of the four inputs
gps_codeCustomer provided a GhanaPostGPS codeRegistry match — see caveats below
hex_codeYou already resolved a location in an earlier sessionSame trust as whatever produced that hex code originally
manualCoordinates you typed in yourselfLowest — no independent capture at all

Full example response​

{
  "success": true,
  "data": {
    "verification_id": "8a2c1e40-…",
    "verified": true,
    "hex_code": "AF-GH-7-0GXTQD5EFZZZZ",
    "ghanapost_code": "GA-142-7281",
    "address": { "region": "Greater Accra", "district": "Accra Metropolitan", "area": "Accra Central" },
    "quality_score": 0.91,
    "verification": { "method": "gps_code", "accuracy_meters": 250, "confidence": "high" },
    "risk_signals": {
      "known_residential_area": true,
      "address_density": "high",
      "previously_verified_by_others": true
    }
  }
}

Field-by-field explanation​

  • verified — the address resolved and met AfriHex's internal threshold for the chosen method. It is not a statement about the customer.
  • quality_score — data completeness (street, area, postcode, coordinates), not ground-truth confirmation — see Identity & KYC's quality score for the exact bands.
  • risk_signals.previously_verified_by_others — true means someone else has previously verified this same address. On its own this is neutral (shared compounds and family houses are normal in Ghana) — it only becomes meaningful combined with your own history of who and how many distinct customers have claimed it.
  • risk_signals.known_residential_area / address_density — characteristics of the area, not the customer. Don't score an individual application down for living somewhere densely populated; that's exactly the geographic-proxy problem discussed in Risk & Fraud's compliance notes.

Error and edge cases​

  • A high quality_score with method: manual. A complete-looking record built from typed-in coordinates carries none of the independent capture a gps_fix would — don't let a high score compensate for a weak method.
  • verified: true but the customer has no photo ID / KYC document check. Address verification and identity document verification are separate claims — this endpoint only ever speaks to the former. Pair it with your own identity-document process for anything regulatory.
  • The address resolves but to a business, not a residence. AfriHex has no concept of "residential vs. commercial" beyond the advisory known_residential_area signal — a resolving address is not evidence the customer lives there. For loan/KYC use cases, corroborate with Proximity verification at least once.
  • Multiple customers verify the same hex_code. Normal in dense housing and shared compounds — don't auto-reject on this alone; it's one input to fraud scoring (see Risk & Fraud), not disqualifying by itself.

Production checklist​

  • A written policy maps quality_score bands + verification.confidence
    • risk_signals to accept/escalate/reject — not an ad hoc if quality_score > 0.8 scattered through the codebase.
  • Every rejection or escalation traceable to a verification_id and a stated reason, for dispute handling and audit (see Identity & KYC — Compliance notes).
  • Nothing in this flow is used, alone, as proof of identity, ownership, residence, creditworthiness, or legality — corroborating evidence (document check, proximity verification, human review) exists wherever the decision matters.
  • Address-based risk signals (known_residential_area, address_density) never feed a decision about an individual applicant who hasn't independently transacted — see the redlining caution in Risk & Fraud.
  • Manual-method verifications are flagged distinctly from device-captured ones wherever method is displayed to a reviewer.

Related endpoints / next guide​