Skip to content
Sendblue Docs
Get Started
API Reference
Location

Watch one shared location

GET/api/location/{number}/watch

Open a Server-Sent Events (SSE) stream for live Find My updates from one contact sharing with a dedicated Mac-backed Sendblue number. Shared lines cannot use this endpoint.

The stream has no client-visible duration. It remains open while the client is connected, authorized, and the worker is available. Comment heartbeats are sent every 15 seconds. Clients should reconnect with their normal credentials after a network interruption or a worker_disconnected completion. Location events are live-only and may repeat across internal native-watch renewals.

Named events and their JSON data payloads:

  • ready: the native watch is active.
  • location: a location state or fix.
  • complete: the watch ended normally. Known reasons are sharing_ended, authorization_revoked, worker_disconnected, and watch_ended. Clients should tolerate additional completion reasons.
  • error: the watch failed after the SSE response started.
Path ParametersExpand Collapse
number: string
Query ParametersExpand Collapse
from_number: string

Your supported Sendblue number in E.164 format

ReturnsExpand Collapse
from_number: optional string

Sendblue line receiving the shared location

location: optional object { accuracy, address, altitude, 6 more }
accuracy: optional number
address: optional string
altitude: optional number
expiresAt: optional string
latitude: optional number
locationType: optional "shallow" or "live" or "legacy" or "unknown"
One of the following:
"shallow"
"live"
"legacy"
"unknown"
longitude: optional number
refreshError: optional string

Present when cached data is returned after a refresh error

timestamp: optional string
message: optional string

Human-readable watch failure

number: optional string

Contact whose location is being watched or changed

reason: optional string

Why the stream ended normally. Known values are sharing_ended, authorization_revoked, worker_disconnected, and watch_ended. Clients should tolerate additional values.

state: optional "not_shared" or "shared_no_fix_yet" or "shared_with_fix"
One of the following:
"not_shared"
"shared_no_fix_yet"
"shared_with_fix"
status: optional "OK" or "ERROR"
One of the following:
"OK"
"ERROR"
LocationWatchResponse object { from_number, location, message, 4 more }

JSON data payload from one named event in a live-location SSE stream

from_number: optional string

Sendblue line receiving the shared location

location: optional object { accuracy, address, altitude, 6 more }
accuracy: optional number
address: optional string
altitude: optional number
expiresAt: optional string
latitude: optional number
locationType: optional "shallow" or "live" or "legacy" or "unknown"
One of the following:
"shallow"
"live"
"legacy"
"unknown"
longitude: optional number
refreshError: optional string

Present when cached data is returned after a refresh error

timestamp: optional string
message: optional string

Human-readable watch failure

number: optional string

Contact whose location is being watched or changed

reason: optional string

Why the stream ended normally. Known values are sharing_ended, authorization_revoked, worker_disconnected, and watch_ended. Clients should tolerate additional values.

state: optional "not_shared" or "shared_no_fix_yet" or "shared_with_fix"
One of the following:
"not_shared"
"shared_no_fix_yet"
"shared_with_fix"
status: optional "OK" or "ERROR"
One of the following:
"OK"
"ERROR"

Watch one shared location

curl https://api.sendblue.co/api/location/$NUMBER/watch \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
Returns Examples