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

# Location updates

> Send one location or a bounded sequence with optional address details.

Location is optional and disabled when omitted. Ask Support to configure the receiving Location
connector, tenant-scoped delivery and Station ID correlation before using it. A location request
without a configured destination returns `400 location_not_configured`.

Use the same dedicated `stationId` configured on the Assist test position. Every location record
uses that station and the top-level `phoneNumber` as ANI; neither can be overridden per record.
Station correlation must select the intended call, not another call with the same ANI.

## One update

```json theme={null}
{
  "stationId": "2202",
  "phoneNumber": "2025550100",
  "callLengthSeconds": 30,
  "location": {
    "latitude": 33.75,
    "longitude": -84.39,
    "address": "124 Maple Street",
    "city": "Springfield",
    "state": "IL"
  }
}
```

## Multiple updates

Use `locations` instead of `location`. Send one to 50 records. `locationStepSeconds` defaults to
five and accepts 1–300 seconds; it is only valid with `locations`.

```json theme={null}
{
  "stationId": "2202",
  "phoneNumber": "2025550100",
  "callLengthSeconds": 30,
  "locationStepSeconds": 5,
  "locations": [
    { "latitude": 33.75, "longitude": -84.39, "address": "124 Maple Street", "city": "Springfield", "state": "IL" },
    { "latitude": 33.7502, "longitude": -84.3901, "address": "124 Maple Street, rear entrance", "city": "Springfield", "state": "IL" }
  ]
}
```

Each record requires finite coordinates: latitude −90 to 90 and longitude −180 to 180. Address
fields are optional printable ASCII without leading/trailing whitespace: `address` up to 128
characters, `city` 64, `state` 32. Null and empty strings are accepted; whitespace-only, padded,
non-ASCII (for example `Montréal`) and control-character values are not. There is no separate
postal-code field; include it in `address` if needed. Location delivery also requires a printable
ASCII station ID. The total 8 KiB request
limit still applies.

## Timing and partial delivery

The first attempt is normally two seconds after recording acceptance (server-configured 1–2
seconds). Each subsequent attempt waits at least `locationStepSeconds` after the previous attempt
finishes. There is no burst catch-up and unsuccessful records are not retried.

The minimum schedule must fit strictly before the call's maximum duration. This is not a delivery
guarantee: I/O can add delay, and audio can finish earlier. Call completion, cancellation or remote
termination stops pending updates. To test a longer location sequence without an early audio end,
omit audio or supply a sufficiently long script within the preparation limits.

For sequence responses, inspect optional progress:

```json theme={null}
{
  "locationProgress": {
    "total": 3,
    "attempted": 2,
    "sent": 2,
    "stopReason": "scenario_completed"
  }
}
```

`attempted` counts durable send claims, including a claim suppressed before a TCP write. `sent`
counts writes whose success was durably recorded. Progress may be absent when unavailable.
`stopReason` is null while pending; outcomes include `all_sent`, `send_failed`, `call_ended`,
`scenario_completed`, `cancelled`, `peer_ended`, `recovery` and `execution_interrupted`.

| `locationSent` | Meaning |
| - | - |
| `true` | All requested records were written to TCP |
| `false` | At least one attempted record failed |
| `null` | No failure observed, but no location was requested or the sequence is incomplete |

> [!WARNING]
>
> TCP write success is not confirmation of parsing, correlation or delivery to the backend.
> Check that each update belongs to the correct active call and position. `Completed` does not
> imply that all location records were sent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.