---
title: "Start a live notification"
method: POST
path: "/v1/live_notifications/start"
tags: ["Live Notifications"]
---

# Start a live notification

`POST /v1/live_notifications/start`

Start a live notification for a profile. Customer.io mints an `instance_id` for the new activity and returns it. You'll use this ID to update, end, or check the status of the activity.

[On iOS](/integrations/sdk/ios/live-activities/set-up/#step-5-start-an-activity), this delivers a push-to-start event through APNs, so the person's device must have a registered push-to-start token for the `notification_type` (the SDK registers one automatically when your app registers the activity type). Push-to-start requires iOS 17.2 or later. iOS starts also require a `push_payload.alert` with a title and body.

[On Android](/integrations/sdk/android/live-notifications/set-up/#step-4-start-a-notification), this delivers an FCM data message, which the SDK renders without your app being open.

## Request body

- object
  - `identifiers` object, required — Identifies the profile you want to start the activity for. You must provide exactly one of `id`, `email`, `phone`, or `internal` (our internal identifier, `cio_` followed by an alphanumeric string). You cannot target anonymous profiles.
    - `id` string — The profile's `id` attribute.
    - `email` string — The profile's email address.
    - `phone` string — The profile's phone number.
    - `internal` string — Our internal identifier for the profile, prefixed with `cio_`.
  - `notification_type` string, required — The reverse-DNS identifier of the activity type, like `io.customer.livenotifications.segments`. Must match a type your app registered with the SDK.
  - `device_id` string — The device token identifying the device to start the activity on.
  - `platform` 'ios' | 'android' — The device platform.
  - `app_identifier` string — The identifier of the app to start the activity on—a bundle ID on iOS or a package name on Android. This only matters when your workspace has multiple apps: set it to target a device belonging to that app, or omit it to target the workspace's default app. Workspaces without multiple apps ignore this field. If you provide a value that doesn't match an app in your workspace, the request fails with a `400`.
  - `attributes` union, required — Static fields used to create the activity—an order number, a flight's origin and destination, or the teams in a match. On iOS they can't change after start. On Android, include the static fields your renderer needs on update and end calls too, because the SDK renders from a merged payload. The shape depends on your `notification_type`: pick the free form variant for iOS or a free form Android activity, or the matching bundled-template variant below. Template fields are documented for [iOS](/integrations/sdk/ios/live-activities/reference/#built-in-templates) and [Android](/integrations/sdk/android/live-notifications/reference/#built-in-templates).
    - object — Your own static fields. On iOS, field names must match the `ActivityAttributes` type in your app. For Android custom types, fields pass through to your app's renderer as-is.
    - object — Static fields for a multi-step tracker template. `notification_type`: `io.customer.livenotifications.segments`.
      - `header` string, required — Top-row label
    - object — Static fields for the countdown timer template. `notification_type`: `io.customer.livenotifications.countdowntimer`.
      - `header` string, required — Top-row label of the notification.
  - `content_state` union, required — The initial dynamic content for the activity—the status, score, or ETA the device renders. Send the complete state on every call; partial updates aren't supported. The shape depends on your `notification_type`: pick the free form variant for iOS or a free form Android activity, or the matching bundled-template variant below. Date fields are epoch seconds.
    - object — Your own dynamic fields. On iOS, field names must match your `ContentState` type. For Android custom types, fields pass through to your app's renderer as-is. Date fields are epoch seconds.
    - object — Dynamic fields for the multi-step tracker template. `notification_type`: `io.customer.livenotifications.segments`.
      - `status` string, required — Primary status line, like `Out for delivery`.
      - `substatus` string — Secondary line under the status.
      - `segmentsTotal` integer, required — The total number of segments in the progress bar. Values above 20 are capped at 20.
      - `segmentsComplete` integer, required — How many segments are filled; the remainder render as incomplete. Values above segmentsTotal are capped at segmentsTotal.
      - `trailingText` string — Short text on the Dynamic Island trailing edge, e.g. \"5 min\". Keep it brief; the trailing region is narrow.
    - object — Dynamic fields for the countdown timer template. `notification_type`: `io.customer.livenotifications.countdowntimer`.
      - `title` string, required — Primary status line.
      - `statusMessage` string — Secondary line under the title.
      - `endTime` integer — Countdown target, in whole seconds since 1970 UTC. A time in the future renders a live countdown; omit it to render no timer. The countdown does not clear itself when it reaches zero — it rests at \"0:00\" until you send an update with a finished title and no endTime.
  - `push_payload` object — The alert shown when the activity starts. Required for iOS.
    - `alert` object
      - `title` string, required — The alert title.
      - `body` string, required — The alert body.
      - `sound` string — The sound to play when the activity starts.
  - `deep_link` string — A link to open when the person taps the activity.
  - `expiration` integer — A unix timestamp (in seconds) for when the activity should expire. Must be no more than 6 hours in the future—values outside the range between now and that 6-hour maximum are rejected with a `400`. If you omit it (or pass `0`), the activity expires 6 hours after it starts.

## Response `200`

The activity was queued. Returns the instance ID for the new activity.

- object
  - `instance_id` string — The unique identifier (ULID) for the new activity instance. Use it to update, end, or check the status of the activity.

## Other responses

- `400` — The request was malformed—a missing required field, an invalid platform, more or fewer than one identifier, or a missing iOS alert.
- `404` — Live notifications aren't enabled for this workspace.

---

[API](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference.md) · [All operations](https://skmtc.dev/customer/apis/customer-io-journeys-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/customer/customer-io-journeys-api-reference/revisions/4b391af7cb06/schema)