Send a location

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

Field	Required	Notes
`phone`	Yes, unless `chat_id` is set	Recipient in E.164 format. Pass either `phone` or `chat_id`, not both.
`chat_id`	Yes, unless `phone` is set	Chert-provided delivery chat id. This is not the public UUID returned by `/api/v1/chats`. Pass either `chat_id` or `phone`, not both.
`latitude`	Yes	Number from `-90` to `90`.
`longitude`	Yes	Number from `-180` to `180`.
`label`	No	Place name shown in the card or text fallback.
`address`	No	Secondary place text.
`url`	No	Custom map URL. Omit unless Chert asks you to override the default Apple Maps link.
`fallback_mode`	No	`auto` is recommended. `balloon` requests a map-card style message; `geo_url` sends plain text; `vcard` is not supported.
`expires_at`	No	Stored and echoed for your own bookkeeping. It does not create an ongoing or expiring Live Location share on the recipient device.
`phone_line_id`	No	Use a specific assigned sender line. Most callers should omit this.
`idempotency_key`	No	Safe retry key for the same location request.
`external_id`	No	Your application record id.

Common errors

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

Get started

Messages

Chats

Group chats

Contact sharing

Webhooks and events

Reference

Send a location

Request

Advanced chat routing

Response

Fields

Common errors

See also

​Request

​Advanced chat routing

​Response

​Fields

​Common errors

​See also

Request

Advanced chat routing

Response

Fields

Common errors

See also