> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a Live Activity

> Start an iOS Live Activity remotely on a contact's iPhone

Starts a Live Activity with push-to-start (iOS 17.2+) on every device of one contact that reported a push-to-start token for `activityType`. Your app reports these tokens once it calls `Sequenzy.observeLiveActivities(of:)` (see [Live Activities](../../concepts/push-notifications#live-activities)). Requires the `transactional:send` scope and APNs credentials in push settings.

Sequenzy adds `sequenzy: { "activityId": "..." }` to the attributes. The SDK reads it to report the new activity's update token under your `activityId`, which [update](./update-live-activity) and [end](./end-live-activity) use.

The request returns `202` once delivery is queued. When no device can start the activity, it still returns `202` with `tokenCount: 0` and sends nothing, so you can fall back to a regular push. Calling start again starts another copy on the same devices; update the running one instead.

## Request

**email** `string`

Contact whose devices start the activity. Provide `email` or `subscriberId`.

**subscriberId** `string`

Subscriber whose devices start the activity.

**activityType** `string` *required*

Your Swift `ActivityAttributes` type name exactly, such as
`DeliveryAttributes`. APNs receives it as `attributes-type`.

**activityId** `string` *required*

Your id for this activity, such as `order-1234`: 1 to 128 letters, digits,
`.`, `:`, `-` or `_`, starting with a letter or digit. Use one id per
person's activity.

**attributes** `object` (default: \{})

Static attributes as JSON, decoded into your attributes struct. A `sequenzy`
key you send is replaced.

**contentState** `object` *required*

Your `ContentState` as JSON. `Date` fields decode as seconds since
2001-01-01, not Unix time, unless your struct decodes them differently.

**alert** `object` *required*

Apple requires an alert to start an activity: `title` and/or `body`, plus an
optional `sound` such as `default`.

**staleDate** `integer | string`

When iOS shows the activity as out of date: Unix seconds or an ISO 8601 date.

**relevanceScore** `number`

Orders a person's concurrent activities; higher shows first. 0 to 1,000,000.

The whole APNs payload must fit in 4 KB, or the request fails with `400`.

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/push/live-activities/start" \
  --header "Authorization: Bearer $SEQUENZY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "jane@example.com",
    "activityType": "DeliveryAttributes",
    "activityId": "order-1234",
    "attributes": { "orderNumber": "1234" },
    "contentState": { "status": "preparing", "minutesAway": 30 },
    "alert": { "title": "Order confirmed", "body": "We are preparing it now." }
  }'
```

## Responses

A body with a missing or mistyped field is rejected with `422` before any other check; invalid ids, dates and the missing contact return `400`.

```json 202 theme={null}
{
  "success": true,
  "event": "start",
  "activityId": "order-1234",
  "tokenCount": 1,
  "jobIds": ["liveact-6c1f-0"],
  "message": "Start queued for 1 device."
}
```

```json 400 theme={null}
{
  "error": "Live Activities are delivered through APNs. Add your APNs key in push settings first."
}
```

```json 401 theme={null}
{
  "error": "Invalid API key"
}
```

```json 422 theme={null}
{ "success": false, "error": "Expected property 'contentState' to be object" }
```

```json 403 theme={null}
{
  "error": "API key is missing required scope: transactional:send"
}
```

```json 404 theme={null}
{
  "error": "Subscriber not found."
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.