Verify a customer's address

POST 
/v2/kyc/verify

Performs instant address verification for KYC compliance. Accepts coordinates, a hex code, or a GhanaPostGPS code. Returns a hex address with quality score, confidence level, risk signals, and real-time fraud detection.

Fraud Detection (NEW): Every verification is analyzed for suspicious patterns:

• Velocity abuse (5+ verifications in 15 min) → BLOCKED
• Geo-impossible travel (>120km/h) → BLOCKED
• Bulk fraud (10+ customers from same IP/hour) → FLAGGED
• Device farm (10+ verifications from same device/hour) → BLOCKED (Requires optional device_id)
• VPN/TOR/Proxy & Datacenter IP detection → FLAGGED
• GPS-IP routing mismatch → SCORED / BLOCKED
• Suspicious travel, manual entry, off-hours activity → SCORED

Transactions with risk_score ≥ 0.8 are automatically blocked. The response includes a fraud_check object with risk score, signals, and recommendation.

The verified field is gated on confidence level: only "high" or "medium" confidence results return verified: true. Low-confidence results (e.g. manual self-reported addresses, GPS codes with quality_score < 0.6) return verified: false. The full response — hex code, address, quality_score, and risk_signals — is always returned regardless, so consuming systems can apply their own thresholds.

Method	Condition	Confidence	Verified
gps_fix	quality_score >= 0.8	high	true
gps_fix	quality_score < 0.8	medium	true
gps_code	quality_score >= 0.6	medium	true
gps_code	quality_score < 0.6	low	false
hex_code	any	medium	true
manual	any	low	false

Replaces $5-7 physical agent visits with a $0.15 API call.

Request

Responses

200

Verification result

400

Missing fields or invalid method/location

403

Fraud-blocked (risk_score >= 0.8) or missing account-scoped API key