Two distinct flows are supported for Live Activities. This page defines the state transitions, the differences between the flows, and which step can be called after which.
Integration flows
Push-to-start flow (API-driven)
The customer triggers the whole flow from its own backend. iOS 17.2+ is mandatory.
update (unlimited)
⤴
│
[REGISTERED] ──/start──▶ [STARTED] ─┴──/update──▶ [STARTED]
│ ▲ │
│ │ │ /end
│ │ /add-users ▼
│ │ /remove-users [DEAD]
│ │ (only │
│ │ before /start) │ /start, /update, /end ──▶ 404 NOT_FOUND
│ └──────────── │
└── /start requires the activity to have been /register-ed firstSDK-first flow (Device-started)
The device application opens the Live Activities itself; the Insider One’s Mobile SDK collects the token and forwards it to Insider together with the activity_type. iOS 16.1+ is sufficient.
(SDK automatic)
[device app opens Live Activities] ──▶ [STARTED] record is created on Insider One
│
┌──────────┼──────────┐
│ │ │
/update /update /end
│ │ │
▼ ▼ ▼
[STARTED] [STARTED] [DEAD]In this flow, /register and /start are not called. When the first token record arrives from the device, the activity automatically enters the STARTED state.
The customer can call /update and /end for this activity.
The record on Insider One's side lives for 1 week. If /end is not called within this period, Insider One does not retain additional data for that activity.
States
State | Description |
|---|---|
REGISTERED | (Push-to-Start only) Created via /register. /start is not called yet. A record exists on Insider One's side, but no push has been sent. /add-users and /remove-users can be called in this state. |
STARTED | The activity is active. Pushes have begun flowing to devices. You can call /update as many times as you want. |
DEAD | /end was called or the validity period has expired. The record on Insider One's side has been deleted. No further operation is possible with the same activity_id. |
Steps
Push-to-start flow
Step | Precondition (state) | Effect | Whether it can be called again |
|---|---|---|---|
POST /register | - | The activity is created (REGISTERED), the segment is recorded, and the device token collection is triggered. The activity has not started yet. | Yes. Each call returns a new activity_id. |
POST /add-user | Activity must be in the REGISTERED state. | New insider_ids are added to the segment; eligibility filters apply. | Yes, unlimited before start |
POST /remove-users | Activity must be in the REGISTERED state. | Devices matching insider_ids are removed from the segment. Idempotent, non-matching IDs are silently skipped. | Yes, unlimited before start |
POST /start | Activity must be in the REGISTERED state | The activity transitions to STARTED; a start push is sent to eligible devices. After this point /add-users and /remove-users cannot be used. | No. A second /start for the same activity_id returns 409 ALREADY_STARTED. |
POST /update | Activity must be in the STARTED state, and≥1 device must be synchronized | An update push is sent; state does not change. | Yes, as often as you want |
POST /end | Activity must be in the STARTED state, ≥1 device must be synchronized | A final push is sent, the record on Insider One's side is deleted, and the activity transitions to DEAD. | No, afterwards 404 NOT_FOUND. |
SDK-first flow
Step | Precondition | Effect |
|---|---|---|
Device app starts a Live Activities + SDK forwards to Insider One | SDK integrated, iOS 16.1+ | A STARTED record is created on Insider One's side; the validity period is 1 week. |
POST /update | Activity STARTED, token present on the device | Content is updated; no sync gate wait. |
POST /end | Activity STARTED | The final push is sent; the record is deleted. |
Critical lifecycle rules
/start is not idempotent (Push-to-start)
A second /start call for the same activity_id is unconditionally rejected with 409 ALREADY_STARTED. Even if the first call hit a network error or timeout, the activity is considered "locked" on the server side.
🔁 Retry strategy: If a /start call times out, do NOT call it again. First check the activity's status (if necessary, call /end and start clean).
/end is irreversible
Once /end returns successfully, the record on Insider One's side is deleted. Every subsequent call with the same activity_id returns 404 NOT_FOUND.
⛔ If you want to start the same segment again, you must create a new activity with /register. The activity_id cannot be reused.
/end does not physically remove the activity from the device
The /end call delivers the final push message to the device and then clears all state on Insider One's side. The live activity on the device disappears according to Apple's stale-after / dismissal-date rules — Insider One does not force-remove the activity from the device screen.
This means your /end message should represent the final state (e.g., package "Delivered", match "Ended"). The user sees this final content until they dismiss the activity or the stale-after period expires.
/add-users and /remove-users only before /start (Push-to-start)
Once the activity transitions to STARTED, the segment is frozen. Users cannot be added to or removed from a started activity. These endpoints can only be used while the activity is in REGISTERED state.
📌 For schema and error code details, see add-users and remove-users.
SDK sync gate (for /update and /end, push-to-start flow)
The push that is sent via /start starts a new live activity on the device. Apple produces a new token for this activity, and the SDK synchronizes it to Insider One. Until this rotation completes, /update and /end messages cannot reach the device.
Situation | Behavior |
|---|---|
Some devices are synchronized, some are not. | Pushes go to the synchronized ones; the rest are counted in skipped_not_synced. 200 OK |
All targeted devices are unsynchronized. | 412 PUSH_TOKEN_NOT_SYNCED |
The lifecycle completes within seconds on actively used devices; it may take longer on backgrounded devices. A 2-5 second buffer between /start and the first /update is recommended. In the SDK-first flow, no waiting is needed; the token is already on the device and /update works immediately.
/register can be repeated for the same activity_type
You can make multiple /register calls with the same activity_type; each returns a new activity_id. You track the number of your active activities yourself; there is no upper limit on the service side (apart from rate limits).
Example case: Order delivery tracking
The following scenario shows all endpoints of the Push-to-Start flow end-to-end on DeliveryActivityAttributes available in the SDK demo app.
An ecommerce customer wants to show the order preparation → courier on the way → delivery stages as a live notification on every customer's device.
Time | Action | Endpoint | Result | Device view |
|---|---|---|---|---|
T - 1 hour | The ordering customer segment is prepared. | POST /register | Eligible devices are collected, and activity_id is returned. Activity is REGISTERED. | No push yet |
T - 30 min | A customer cancels their order. | POST /remove-users | Devices belonging to that insider_id are removed from the segment. | - |
T - 30 min + 5 min | Freed stock is assigned to another order. | POST /add-users | The new customer's devices are added to the segment. | - |
T + 0 | Order preparation begins. | POST /start (status: "pickup") | "Your order is being prepared" live activity push goes out. Transitions to STARTED. After this point /add-users and /remove-users cannot be used. |
|
T + 15 min | The courier sets off. | POST /update (status: "in_transit") | "Courier on the way" update. |
|
T + 35 min | Approaching the address | POST /update (status: "out_for_delivery") | "Out for delivery — at your door soon" update. |
|
T + 45 min | Delivered | POST /end (status: "delivered") | "Order delivered — enjoy!" final message. The activity is deleted on Insider One's end; the live activity on the device disappears per Apple's rules. |
|
.png)
The same pattern applies to the other demo activities. For example, for Workout (training phase tracking) and Match (live score), the flow is identical. Only the content_state fields and enum values change.