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. There is no endpoint that lists device_type_ids — 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 — POST /panic-api/v2/devices
• Update a linked device — PUT /panic-api/v2/devices
• Unlink a 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 (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:

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:

1
{
2
  "device_type_id": 1,
3
  "device_id": "A1B2C3D4",
4
  "message_type": 1,
5
  "location": { "latitude": -26.10911, "longitude": 28.053037, "sequenceNumber": "46" }
6
}

Update the callout location:

1
{
2
  "device_type_id": 1,
3
  "device_id": "A1B2C3D4",
4
  "message_type": 2,
5
  "body": { "latitude": -26.2025, "longitude": 28.0468, "sequenceNumber": "47" }
6
}

Cancel the callout:

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

Report a battery / health update:

1
{ "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 for request and response examples of each event type.