> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychert.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a location

> POST /api/v1/locations - send a one-time location pin.

Sends a one-time location pin to a phone number when location sharing is enabled on the selected sender line.

<Warning>
  This is not Find My or ongoing Live Location sharing. It sends one fixed latitude/longitude. The recipient cannot follow movement from this endpoint.
</Warning>

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

```bash theme={null}
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`.

```json theme={null}
{
  "chat_id": "iMessage;+;chat42",
  "latitude": 40.758896,
  "longitude": -73.985130,
  "label": "Times Square"
}
```

## Response

```json theme={null}
{
  "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. |

## See also

* [Sending](/api/sending)
* [Create a chat](/api/chats/create)
* [Send a message](/api/chats/send-message)
* [Errors](/api/errors)