> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aurasos.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aurasos.com/_mcp/server.

# Callout lifecycle

A **callout** is AURA's **on-demand** emergency-response request (as opposed to a
[scheduled service](/overview/core-concepts/scheduled-services)). When you create one, AURA's
control room dispatches a responder and tracks the incident through to
resolution. This guide describes the stages a callout moves through; each links
to the API Reference for the exact request and response.

## Create a callout

Create a callout for a customer with a response type and a location. A callout
takes either **live coordinates** (`latitude`/`longitude`) or a
**`predefinedLocationId`** for a Fixed Location — not both. Live callouts require
the customer to have an **active subscription**.

Two behaviours worth designing for:

* If the customer **already has an active callout**, creating another returns
  the existing callout instead of opening a second incident.
* For some integrations a legacy **try-before-signup** grace applies: a
  customer's *first* callout can succeed without a subscription so the service
  can be experienced before payment. Do not design around it — activate the
  subscription at onboarding and treat the grace as a transitional behaviour
  only available by arrangement.

For Fixed Location emergencies, create it against a Fixed Location instead (see
[Fixed Locations](/property-protect/fixed-locations)).

Reference:
[Create a customer callout](/api-reference/callouts/create-customer-callout).

```mermaid
flowchart LR
    A[Create callout] --> B{Authorised?}
    B -- No --> B1[401 — invalid token or response type not linked]
    B -- Yes --> C{Valid request?}
    C -- Yes --> OK[Callout created]
    C -- No --> E1[400 — invalid location or response type]
    C -- No --> E3[403 — no active subscription]
```

## Keep the callout location current

While a callout is active, keep its location current by submitting the
customer's latest coordinates as they move. There are two location-update
operations:

* **Update callout location** — submits the coordinates only.
* **Update callout location and return callout** — submits the coordinates
  *and* returns the latest callout state in the same call, designed for
  **polling** while a callout is active.

Reference:
[Update callout location](/api-reference/callouts/update-callout-location),
[Update callout location and return callout](/api-reference/callouts/update-callout-location-and-return).

Once a callout is **closed**, further location updates are rejected with Panic
API's custom HTTP `285` status (the latest callout state is still returned), so
you can stop polling.

## Track progress

Follow a callout in one of two ways:

* **Poll** — call *Update callout location and return callout* (or *Get a
  callout*) to read the current state on an interval.
* **Subscribe to webhooks** to receive lifecycle events as they happen — see the
  [Webhooks](/overview/core-concepts/webhooks) guide. Webhooks avoid polling and are preferred
  for server-to-server integrations.

In-callout events (comments, status notes) are exchanged through the callout's
event stream.

> **Warning**
>
> The **read** endpoints return a richer, nested shape than the creation
> response: incident, location, and dispatch detail are grouped under
> `incidentInformation[]` (with `calloutCurrentLocation` and
> `dispatchInformation`). Don't reuse your create-response model when polling —
> see *Get a callout* in the API Reference for the exact schema.

Reference:
[Get a callout](/api-reference/callouts/get-callout-by-id),
[Read callout events](/api-reference/callout-events/list-callout-events),
[Send a callout event](/api-reference/callout-events/create-callout-event).

## Callout statuses

Rounded nodes are `status` values the API returns. Diamonds are decisions taken
inside AURA, not statuses — you will never see them in a payload.

```mermaid
flowchart LR
    A[/Create callout/] --> B([created])
    B --> C{Response required?}
    C -- No --> Z([closed])
    C -- Yes --> D([Responder Dispatched])
    D --> E{Response still required?}
    E -- No --> F([Responder Cancelled])
    E -- Yes --> G{Another responder should proceed?}
    G -- Yes --> P([pending])
    P -- A specific supplier is chosen --> D
    P -- No supplier chosen, or a specific responder is rung --> B
    G -- No --> H([Responder Arrived])
    H --> I([Responder Completed])
    I --> Z
    F --> Z
```

A callout's `status` field moves through these states. The values are returned
**exactly as shown** — note the mixed casing (`created`, `closed`, `pending` and
`acknowledged` are lowercase; the responder states are title case), so compare
them exactly.

### Redistribution, and why status is not forward-only

When a dispatched responder stands down or the control centre moves the callout to
someone else, AURA **redistributes** it. Redistribution always parks the callout on
`pending` first, then lands on one of two states depending on what was chosen:

| What the control centre does              | Status path                                                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Redistributes without choosing a supplier | `Responder Dispatched` → `pending` → `created`                                                          |
| Dispatches to a specific supplier         | `Responder Dispatched` → `pending` → `Responder Dispatched`                                             |
| Rings a specific responder                | `Responder Dispatched` → `pending` → `created`, then `Responder Dispatched` once that responder accepts |
| Cancels the response outright             | `Responder Dispatched` → `Responder Cancelled` (no `pending` step)                                      |

So a normal sequence can include `created` → `Responder Dispatched` → `pending` →
`created` → `Responder Dispatched`. Treat `created`, `pending` and
`Responder Dispatched` as **active and in progress**. Do not interpret `pending`,
or a return to `created`, as a new callout or as a terminal failure.

`pending` is also the status of a callout created with dispatch deferred, so it is
not exclusively a redistribution state.

| Status                 | Meaning                                                                                             |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| `created`              | AURA has received the callout and it is awaiting dispatch or redispatch.                            |
| `pending`              | Transient. The callout is being redistributed, or was created with dispatch deferred. Still active. |
| `acknowledged`         | The control centre has acknowledged the callout.                                                    |
| `Responder Dispatched` | A responder has been allocated and is en route.                                                     |
| `Responder Arrived`    | The responder is on scene assisting the customer.                                                   |
| `Responder Completed`  | The responder has finished and is no longer needed on scene.                                        |
| `Responder Cancelled`  | The dispatched responder is confirmed no longer required.                                           |
| `closed`               | The control centre has confirmed no further help is needed; the callout is complete.                |

You may occasionally observe other transient statuses while polling — treat any
unknown value as in-progress rather than terminal.

Stop sending location updates once a callout is `closed`.

## Callout tracking

When you create a callout with initial coordinates, the response includes a hosted
tracking URL for real-time tracking — see
[Callout tracking](/overview/embedded-flows/callout-tracking).

## Cancel a callout

Cancel a callout when it is no longer needed. There are two modes:

* **Customer cancellation** — supply a `safeCode` (the last four digits of the
  customer's registered mobile number) to confirm the cancellation came from the
  customer.
* **Integration cancellation** — cancel without a safe code from a trusted
  backend, optionally with exception reasons for the dispatch record.

Reference:
[Cancel a callout](/api-reference/callouts/cancel-callout).

## Collect a rating

Capture customer feedback on the response to close the loop. Ratings are
summarised for you in the AURA portal (average, distribution, and trend over time).

Reference:
[Submit a callout rating](/api-reference/callout-ratings/create-callout-rating).

![Ratings dashboard showing average rating, rating counts, and monthly trend](/_fern-img/6c5d8d4fd456abc91886dc269c85aad62a417d0cc54b251cce39bcf345d762ee.webp)