POST /start

This request actually starts an activity that was prepared via /register.

• It transitions the activity to the STARTED state (an atomic lock is stamped).

• Sends the first live activity push via Apple to all eligible devices in the segment, or to selected devices when filtered by target_devices.

• The live activity is opened and becomes visible on the device at this point.

Insider One acts as a proxy for the content: all values in the content field are passed directly into the Apple push payload.

Endpoint and headers

POST /api/v1/live-activity/start

Headers

Body parameters

Below are the parameters for the request body.

• When target_devices is present, pushes are sent only to devices matching the (insider_id, udid) pairs in the list. Omit this field to push to the whole segment.

• activity_id cannot be empty.

• activity_type cannot be empty.

Sample body

Below is a sample request body.

{
  "activity_id": "550e8400-e29b-41d4-a716-446655440000",
  "activity_type": "OrderTrackingAttributes",
  "content": {
    "title": "Your order is being prepared",
    "message": "Estimated delivery: 14:30",
    "content_state": {
      "status": "preparing",
      "eta": "2026-05-20T14:30:00Z"
    }
  }
}

{
  "activity_id": "550e8400-e29b-41d4-a716-446655440000",
  "activity_type": "OrderTrackingAttributes",
  "content": {...},
  "target_devices": [
    {
      "insider_id": "user-123",
      "udid": "abc-device-1"
    },
    {
      "insider_id": "user-456",
      "udid": "def-device-2"
    }
  ]
}

Body examples

Below are /start body examples for the 3 activities in the SDK demo app. All enum cases and content_state field names match the iOS classes exactly.

Order is being prepared

{
  "activity_id": "<activity_id from register response>",
  "activity_type": "DeliveryActivityAttributes",
  "content": {
    "title": "Your order is being prepared",
    "message": "Courier on the way — will pick up shortly",
    "content_state": {
      "status": "pickup",
      "etaMinutes": 45
    },
    "attributes": {
      "courierName": "John D."
    }
  }
}

Workout warmup phase

{
  "activity_id": "<activity_id from register response>",
  "activity_type": "WorkoutActivityAttributes",
  "content": {
    "title": "Workout started",
    "message": "Running · warmup phase",
    "content_state": {
      "phase": "warmup",
      "elapsedSeconds": 0,
      "calories": 0
    },
    "attributes": {
      "workoutType": "Running"
    }
  }
}

The match's first half kicked off

{
  "activity_id": "<activity_id from register response>",
  "activity_type": "MatchActivityAttributes",
  "content": {
    "title": "Match started",
    "message": "Home FC 0 - 0 Away FC",
    "content_state": {
      "homeScore": 0,
      "awayScore": 0,
      "period": "first_half",
      "minute": 1
    },
    "attributes": {
      "homeTeam": "Home FC",
      "awayTeam": "Away FC"
    }
  }
}

Critical rules

Idempotency: A second /start is rejected

A second /start call for the same activity_id unconditionally returns 409 ALREADY_STARTED. Even if the first call hit a network error or timeout, the activity is considered "locked" on the server side.

{
  "error": "activity already started",
  "code": "ALREADY_STARTED"
}

Do not retry /start after a timeout. The activity may already be locked. To restart the same segment, call /end first, then run a fresh /register + /start flow.

Proxy behavior

Content responsibility lies with the customer. Insider One passes the values inside the content as-is to the Apple push payload:

• It does not validate the content.

• It does not translate/localize.

• It does not modify value formats.

• It does not retain it persistently.

Insider is not liable for any user-experience issues caused by wrong, missing, or inappropriate content.

content_state enum matching

All values inside content_state must be compatible with the ContentState struct in the iOS application. In particular for enum-typed fields:

• Enum case names must match exactly (case-sensitive).

• Wrong cases cause silent failures in the Apple decoder. Insider One cannot detect the mismatch.

iOS side example

enum OrderStatus: String, Codable {
    case preparing
    case onTheWay
    case delivered
}

Correct on the API side

{ "status": "onTheWay" }

Wrong (device crash or silent failure)

{ "status": "on_the_way" }
{ "status": "ontheway" }
{ "status": "OnTheWay" }

Must be registered first

If the activity is not present on Insider's side at the time of /start (not registered or already ended), 404 NOT_FOUND is returned. The flow must run in the correct order:

/register → get activity_id → /start

Sample responses

Success response 200

{
  "status": "success",
  "sessions_triggered": 850
}

Below are the fields that return in the response.

sessions_triggered indicates the push has been handed off to Apple.

Error responses

Refer to Error Codes for details.

Limitations

• The rate limit is 1,000 requests per minute.

• activity_id is opaque. Use only the value returned from the /register response.

• No device sync is required before /start. Devices are ready for activation via their push-to-start tokens. The sync gate only applies to /update and /end.

• Broadcast vs targeted: When target_devices is empty, a broadcast is performed to all eligible devices in the segment. To send to a sub-segment, populate the list. In targeted mode, eligibility (sync, opt-in) is still checked.

• Apple-side drops do not reflect in sessions_triggered. This counter shows successful handoffs; failures to reach the device (token-invalid, network) are tracked on Insider One's end and will be exposed in a future release.