Skip to main content

Background location report

POST 
/v2/location/ping

Lightweight endpoint called by the bank's mobile SDK in the background. Validates consent, computes hex cell, checks for zone drift, and fires webhook if the customer has moved. Designed for high throughput with minimal response payload.

No-fix heartbeat (going dark). If the device has no location (GPS / location services off, or permission denied), still send a ping with lat: 0, lng: 0 (optionally source: "none"). The server does not reject it — instead it:

  • falls back to a coarse IP-based geolocation (city-level, derived server-side from the connection, so it works even with GPS off), and
  • fires a location_unavailable webhook so the lender is notified immediately that the borrower's device is connected but dark, rather than waiting for a staleness timeout.

The response status is then location_unavailable (instead of ok). Keep heartbeating on the returned next_ping_in schedule even with no fix, so going dark stays visible.

Cost: $0.02–0.05 per ping.

Request​

Responses​

Ping accepted. status is ok for a normal fix, location_unavailable for a no-fix heartbeat, or consent_expired / consent_revoked.