ProximityVerifyResponse

verification_idstring

UUID of the persisted verification record. Empty for early-exit results (INVALID_FORMAT, ADDRESS_NOT_FOUND).

resultstring

Possible values: [NEAR, FAR, ADDRESS_NOT_FOUND, INVALID_FORMAT]

verifiedboolean

True iff result == NEAR AND confidence >= 0.60.

confidencenumber<double>

0.0–1.0. Computed from the rubric, then capped by accuracy and spoof_risk.

declared_address object

gps_codestring

existsboolean

latnumber<double>

lngnumber<double>

regionstring

districtstring

areastring

quality_scorenumber<double>

proximity object

device_distance_minteger

Haversine distance in meters between device and resolved address.

gps_accuracy_mnumber<double>nullable

Echoed from request — caller can log input quality.

accuracy_sufficientbooleannullable

True iff gps_accuracy_m <= 100. Null when accuracy was not provided.

tiers object

within_50mboolean

within_100mboolean

within_500mboolean

within_1kmboolean

confidence_factors object

Boolean inputs to the confidence rubric. Each true factor contributes its documented weight. Surfaced in the response so callers can audit why a score was what it was.

address_existsboolean

device_within_1kmboolean

device_within_500mboolean

device_within_100mboolean

device_within_50mboolean

gps_accuracy_providedboolean

gps_accuracy_under_25mboolean

gps_accuracy_under_10mboolean

mock_location_offboolean

provider_is_hardwareboolean

location_fix_freshboolean

altitude_non_zeroboolean

no_fraud_signalsboolean

integrity object

spoof_riskstring

Possible values: [LOW, MEDIUM, HIGH]

flagsstring[]

Names of failed/suspicious checks. Possible values: mock_location_detected, gps_accuracy_insufficient, altitude_zero, speed_inconsistent, location_stale, ip_location_mismatch, timezone_mismatch.

checks object

mock_locationstring

gps_accuracystring

altitude_plausiblestring

speed_consistentstring

location_freshnessstring

ip_location_matchstring

NOT_PROVIDED in v1; planned for v2 alongside IPIntelligence wiring.

timezone_matchstring

fraud_check object

Real-time fraud detection analysis result

blockedboolean

Whether the transaction was blocked (risk_score >= 0.8)

Example: false

risk_scorenumber<double>

Cumulative risk score from all detected signals

Possible values: >= 0 and <= 1

Example: 0.25

risk_levelstring

Risk classification based on score thresholds

Possible values: [low, medium, high, critical]

Example: low

signals object[]

Individual fraud signals detected

Array [

typestring

Signal type identifier

Possible values: [velocity_abuse, velocity_suspicious, impossible_travel, suspicious_travel, bulk_fraud, new_customer, manual_entry, off_hours]

Example: new_customer

severitystring

Signal severity level

Possible values: [low, medium, high, critical]

Example: low

descriptionstring

Human-readable explanation of the signal

Example: First verification for this customer

scorenumber<double>

Contribution to total risk score

Example: 0.1

]

recommendationstring

Human-readable action recommendation

Example: Approve transaction

degradedboolean

True when one or more fraud sub-checks (velocity, IP/device bulk, synthetic-identity) could not run — e.g. a transient DB error — so risk_score reflects fewer signals than usual. These sub-checks fail open rather than blocking the verification, so this is what makes that visible instead of a degraded check looking clean.

Example: false

degraded_checksstring[]

Which sub-checks were skipped, when degraded is true.

Possible values: [velocity, ip_velocity, device_velocity, synthetic_identity]

Example: []

certificate object

Short reference embedded in the proximity response so callers know where to fetch and verify the full certificate.

idstring

verification_urlstring

Public verification endpoint (no auth required).

json_urlstring

Full signed certificate JSON (auth required).

pdf_urlstring

PDF certificate with embedded QR code (auth required).

jwks_urlstring

JWK Set used to verify the signature.

issued_atstring

retention object

Retention duration and legal basis, surfaced in the response so compliance teams can audit the data lifecycle without a separate documentation lookup.

verification_storedboolean

retention_periodstring

data_retainedstring[]

retention_legal_basisstring

provenance object

A normalized summary of what confidence_factors/integrity already compute in detail. source is always device_gps here — a spoofed or low-accuracy fix is still categorically a device-reported claim, just one confidence (reused from the top-level field, not recomputed) and integrity.spoof_risk already score as untrustworthy.

sourcestring

device_gps: a live GPS/network/fused fix reported by a device at request time. geocoded_text: inferred purely from parsing/matching text or grid math, no real-world confirmation. third_party_match: matched against an external dataset (OSM, Google Open Buildings, GhanaPostGPS's own registry) without independent confirmation on the ground. user_confirmed: explicitly entered/confirmed by the address owner. agent_verified: independently confirmed by a human or a real event — a field agent's manual promotion, a signed proof-of-delivery — the strongest tier.

Possible values: [device_gps, geocoded_text, third_party_match, user_confirmed, agent_verified]

Example: agent_verified

providerstring

The upstream/system that produced the point (e.g. "ghanapostgps", "osm", "google_open_buildings", "customer_app"), separate from source's trust tier.

Example: ghanapostgps

accuracy_metersnumber<double>

A physical measurement (GPS accuracy, computed drift, snap distance) — independent of confidence.

confidencenumber<double>

Trust score, 0.0–1.0.

Possible values: >= 0 and <= 1

Example: 0.85

verified_atstring<date-time>

timestampstring<date-time>

ProximityVerifyResponse
{
  "verification_id": "string",
  "result": "NEAR",
  "verified": true,
  "confidence": 0,
  "declared_address": {
    "gps_code": "string",
    "exists": true,
    "lat": 0,
    "lng": 0,
    "region": "string",
    "district": "string",
    "area": "string",
    "quality_score": 0
  },
  "proximity": {
    "device_distance_m": 0,
    "gps_accuracy_m": 0,
    "accuracy_sufficient": true,
    "tiers": {
      "within_50m": true,
      "within_100m": true,
      "within_500m": true,
      "within_1km": true
    }
  },
  "confidence_factors": {
    "address_exists": true,
    "device_within_1km": true,
    "device_within_500m": true,
    "device_within_100m": true,
    "device_within_50m": true,
    "gps_accuracy_provided": true,
    "gps_accuracy_under_25m": true,
    "gps_accuracy_under_10m": true,
    "mock_location_off": true,
    "provider_is_hardware": true,
    "location_fix_fresh": true,
    "altitude_non_zero": true,
    "no_fraud_signals": true
  },
  "integrity": {
    "spoof_risk": "LOW",
    "flags": [
      "string"
    ],
    "checks": {
      "mock_location": "string",
      "gps_accuracy": "string",
      "altitude_plausible": "string",
      "speed_consistent": "string",
      "location_freshness": "string",
      "ip_location_match": "string",
      "timezone_match": "string"
    }
  },
  "fraud_check": {
    "blocked": false,
    "risk_score": 0.25,
    "risk_level": "low",
    "signals": [
      {
        "type": "new_customer",
        "severity": "low",
        "description": "First verification for this customer",
        "score": 0.1
      }
    ],
    "recommendation": "Approve transaction",
    "degraded": false,
    "degraded_checks": []
  },
  "certificate": {
    "id": "string",
    "verification_url": "string",
    "json_url": "string",
    "pdf_url": "string",
    "jwks_url": "string",
    "issued_at": "string"
  },
  "retention": {
    "verification_stored": true,
    "retention_period": "string",
    "data_retained": [
      "string"
    ],
    "retention_legal_basis": "string"
  },
  "provenance": {
    "source": "agent_verified",
    "provider": "ghanapostgps",
    "accuracy_meters": 0,
    "confidence": 0.85,
    "verified_at": "2024-07-29T15:51:28.071Z"
  },
  "timestamp": "2024-07-29T15:51:28.071Z"
}