ProximityVerifyResponseWrapper

successboolean

data object

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>

meta object

request_idstring<uuid>

Unique request identifier

Example: c86825f0-d8ca-4ae1-8226-514cc48e05c0

cachedboolean

Whether the response was served from cache

Example: false

latencystring

Server-side processing time

Example: 1.802457582s

boundary_distance_mnumber<double>nullable

Reverse-geocode responses only. Distance in metres from the queried coordinate to the nearest edge of the resolved GhanaPostGPS grid cell. Omitted when the upstream response carried no cell bounds.

Example: 1.42

near_grid_boundaryboolean

Reverse-geocode responses only. True when boundary_distance_m is small enough that an ordinary GPS fix's jitter could plausibly have resolved to the neighbouring cell's code instead — the documented cause of the same property getting different GhanaPostGPS codes depending on where you stand.

Example: false

ProximityVerifyResponseWrapper
{
  "success": true,
  "data": {
    "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"
  },
  "meta": {
    "request_id": "c86825f0-d8ca-4ae1-8226-514cc48e05c0",
    "cached": false,
    "latency": "1.802457582s",
    "boundary_distance_m": 1.42,
    "near_grid_boundary": false
  }
}