> 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.

# IoT Devices

Connect physical IoT devices (panic buttons, wearables, trackers) to AURA so a
device press can create and manage callouts. AURA normalises each device's native
messages into AURA actions using a **device template**, so you don't have to map
hardware protocols yourself.

## Before you start

Device onboarding is collaborative — AURA registers your device offering first
and gives you the identifiers you'll send on every event:

* **`device_id`** — the device's message identifier. This is **derived from the
  device serial** by the template (typically a substring extraction defined at
  onboarding), so it is usually *not* the full serial. The link-device response
  returns the derived value as `deviceId` — send that on every event.
* **`device_type_id`** — identifies the device model, and selects the template
  AURA uses to interpret its messages. In the link-device request, this is
  exposed as `deviceType`.
* **`deviceSupplier`** — the device brand.

You'll also need your `clientId` / `clientSecret` to
[authenticate](/overview/core-concepts/authentication). There is no endpoint that
lists `device_type_id`s — AURA provides the ones registered to you. To get set
up, contact your AURA integration team.

The device serial you link must match the device template AURA has registered
for your customer source. The public examples below are illustrative; use the
actual serial, supplier, and device type provided during onboarding.

If the serial or template has not been provisioned yet, the link request can
fail even when the JSON shape is valid.

## Linking a device

Link a device to a customer so it can act on their behalf, then manage that link
over time:

* [Link a device](/api-reference/iot-devices/link-device-to-customer) — `POST /panic-api/v2/devices`
* [Update a linked device](/api-reference/iot-devices/update-device-for-customer) — `PUT /panic-api/v2/devices`
* [Unlink a device](/api-reference/iot-devices/unlink-device) — `DELETE /panic-api/v2/devices/{deviceId}`

The link request requires `customerId`, `deviceSerial`, and `deviceSupplier`
(`deviceType` is optional — when omitted, AURA resolves it from the supplier).
The response includes the derived `deviceId` used in device events.

## Sending device events

Every other interaction — creating a callout, updating location, cancelling, or
reporting battery/health — flows through a single endpoint:
[Send a device event](/api-reference/iot-devices/create-device-event)
(`POST /panic-api/v2/deviceEvent`). AURA applies the device's template (by
`device_type_id`) to interpret the incoming message and map it to an AURA action:

| Action           | Resolved event                 | Meaning                                     |
| ---------------- | ------------------------------ | ------------------------------------------- |
| New callout      | `NEW_CALLOUT`                  | Create a callout from the device's location |
| Location update  | `CALLOUT_LOCATION_UPDATED`     | Update an active callout's location         |
| Cancel callout   | `CALLOUT_CANCELLED`            | Cancel the device's active callout          |
| Battery / health | `DEVICE_BATTERY_INFO_RECEIVED` | Record a battery level or heartbeat         |

The exact message-to-action mapping — including the `message_type` values and
**where the payload fields live** — is defined by your device template and
agreed during onboarding. The examples below use a typical template where
`message_type` 1–4 select the actions above, the new-callout payload is carried
in a `location` object, and the other events carry theirs in `body`. Your
template may differ.

The response echoes your `input` and returns a `resolvedAuraEvent` with the
mapped `eventTypes` and an `eventResponse` (e.g. the created `calloutId`). If
the device already has an active callout, a new-callout event resolves to that
existing callout.

### Examples

Create a callout:

```json
{
  "device_type_id": 1,
  "device_id": "A1B2C3D4",
  "message_type": 1,
  "location": { "latitude": -26.10911, "longitude": 28.053037, "sequenceNumber": "46" }
}
```

Update the callout location:

```json
{
  "device_type_id": 1,
  "device_id": "A1B2C3D4",
  "message_type": 2,
  "body": { "latitude": -26.2025, "longitude": 28.0468, "sequenceNumber": "47" }
}
```

Cancel the callout:

```json
{ "device_type_id": 1, "device_id": "A1B2C3D4", "message_type": 3, "body": { "sequenceNumber": "48" } }
```

Report a battery / health update:

```json
{ "device_type_id": 1, "device_id": "A1B2C3D4", "message_type": 4, "body": { "batteryLevel": 72 } }
```

### Raw device-gateway payloads

Some legacy templates parse a device's native gateway payload directly (for
example raw Sigfox uplinks with hex `data` frames) instead of the structured
shape above. If your devices emit raw payloads, AURA configures the parsing
template during onboarding — confirm the exact fields with your AURA contact.

See the [reference](/api-reference/iot-devices/create-device-event)
for request and response examples of each event type.