Skip to main content
Sends a one-time location pin to a phone number when location sharing is enabled on the selected sender line.
This is not Find My or ongoing Live Location sharing. It sends one fixed latitude/longitude. The recipient cannot follow movement from this endpoint.
Use this when you already have coordinates and want the recipient to receive a Maps-style location card when their sender line supports it. With fallback_mode: "auto", Chert can fall back to a normal Apple Maps URL after an enabled sender line accepts the request. If the selected sender line does not support location sends, Chert returns 4099.

​
Request

curl -X POST https://console.trychert.com/api/v1/locations \
  -H "Authorization: Bearer $CHERT_SIGNING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+14155551234",
    "latitude": 40.758896,
    "longitude": -73.985130,
    "label": "Times Square",
    "address": "Manhattan, NY",
    "fallback_mode": "auto",
    "expires_at": "2026-06-02T23:00:00Z",
    "idempotency_key": "loc-2026-06-02-001"
  }'

​
Advanced chat routing

Most callers should send by phone. chat_id is only for Chert-provided delivery chat ids; it is not the UUID returned by POST /api/v1/chats. 
{
  "chat_id": "iMessage;+;chat42",
  "latitude": 40.758896,
  "longitude": -73.985130,
  "label": "Times Square"
}

​
Response

{
  "message_id": "msg_01H...",
  "status": "queued",
  "phone_line_id": "pl_15555550100",
  "delivery": "queued",
  "location": {
    "latitude": 40.758896,
    "longitude": -73.98513,
    "label": "Times Square",
    "address": "Manhattan, NY",
    "mode": "balloon",
    "fallback_mode_requested": "auto"
  }
}
202 means the location request was accepted by the sender line. The final recipient UI is device-dependent: supported iMessage clients may render a map card; fallback clients receive a tappable Apple Maps URL.

​
Fields

FieldRequiredNotes
phoneYes, unless chat_id is setRecipient in E.164 format. Pass either phone or chat_id, not both.
chat_idYes, unless phone is setChert-provided delivery chat id. This is not the public UUID returned by /api/v1/chats. Pass either chat_id or phone, not both.
latitudeYesNumber from -90 to 90.
longitudeYesNumber from -180 to 180.
labelNoPlace name shown in the card or text fallback.
addressNoSecondary place text.
urlNoCustom map URL. Omit unless Chert asks you to override the default Apple Maps link.
fallback_modeNoauto is recommended. balloon requests a map-card style message; geo_url sends plain text; vcard is not supported.
expires_atNoStored and echoed for your own bookkeeping. It does not create an ongoing or expiring Live Location share on the recipient device.
phone_line_idNoUse a specific assigned sender line. Most callers should omit this.
idempotency_keyNoSafe retry key for the same location request.
external_idNoYour application record id.

​
Common errors

CodeWhen
1001Missing phone/chat_id, or missing coordinates.
1002Both phone and chat_id were passed, or coordinates are out of range.
3002No eligible sender line is available for location sharing.
4001The sender line accepted the request but delivery failed downstream.
4099Location sharing is not available on the selected sender line, or the requested mode is unsupported.

​
See also