Skip to main content

Proximity verification (declared address vs device GPS)

POST 
/v2/verify/proximity

Compares a declared GhanaPostGPS address against the device's reported GPS fix and returns a numeric confidence score, integrity verdict, and retention metadata. Designed as the v1 primitive of the address- verification product — intended for one-shot use at onboarding and on a recurring cadence as part of ongoing due diligence (per BoG Supervisory Guidance Note Oct 2025).

Confidence rubric is fully exposed in the response (confidence_factors) so compliance teams can audit why a call scored what it did. Each factor below contributes its weight when true; the lowest applicable hard cap then wins.

FactorWeight
address_exists+0.30
device_within_1km+0.10
device_within_500m+0.10
device_within_100m+0.10
device_within_50m+0.10
gps_accuracy_provided AND accuracy < 25m+0.10
gps_accuracy_provided AND accuracy < 10m+0.05
mock_location_off+0.05
provider_is_hardware+0.03
location_fix_fresh (< 5s old)+0.02
altitude_non_zero+0.02
no_fraud_signals+0.03

Hard caps (applied after the rubric, lowest cap wins):

  • gps_accuracy_m > 100 → cap at 0.60 (noisy fix is not signal)
  • spoof_risk == HIGH → cap at 0.30 (known spoofer cannot pass)
  • spoof_risk == MEDIUM → cap at 0.50

verified is true iff result == "NEAR" AND confidence >= 0.60.

Result codes:

  • NEAR — device is within 1 km of the resolved address
  • FAR — address resolved but device > 1 km away
  • ADDRESS_NOT_FOUND — well-formed code that didn't resolve
  • INVALID_FORMAT — code didn't match the expected pattern

See docs/PROXIMITY_VERIFY.md for the full reference.

Request​

Responses​

Verification result (always 200; result code distinguishes outcomes)