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. On the newer location-card-enabled lines, auto selects the card path and a failure does not automatically send a URL. Choose geo_url explicitly for URL-only delivery. Other enabled lines can retain their existing auto fallback behavior. If the selected sender line does not support location sends, Chert returns 4099.

Request

Location-card-enabled lines

The existing native location-card rollout is enabled on selected lines. It requires phone in E.164 form, an existing direct iMessage chat belonging to the sender, and a nonempty idempotency_key up to 128 characters. Groups, email recipients, chat_id, custom url, and vcard are not supported on this path. An accepted request returns 202 with message_id, status, delivery, location, and status_url. Read the returned status_url (GET /api/v1/locations/{message_id}) with the same authentication to inspect recorded queued/acknowledged/sent/delivered evidence. Acceptance or acknowledgement is not recipient rendering. This status route applies to the enabled card path; do not assume every older location response includes it. Preserve the same key and original request. A changed key creates another send. After an uncertain result or retryable: false, reconcile before sending again; do not automatically downgrade a requested card to a URL.

Advanced chat routing — other enabled lines

Use this section only when Chert confirms the line supports this legacy routing. Location-card-enabled lines reject chat_id. 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.

Response — existing location path

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

Common errors

See also