openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io App Live Notifications API
  description: 'Our App API provides ways to trigger messages and retrieve information about people, campaigns, broadcasts, and more.


    # Overview


    The App API provides methods to send newsletters, transactional messages, and API-triggered broadcasts. You can create newsletters from scratch and update transactional messages and API-triggered broadcasts.


    For transactional messages and API-triggered broadcasts, your payload acts as a message "trigger" and can contain `data` that you reference in your messages using liquid—`{{trigger.<data>}}`.


    The other endpoints help you retrieve information about people, segments, campaigns, broadcasts, etc; it also lets you update campaign actions, messages, newsletter variants, etc. Aside from the [API-triggered broadcast](#triggerBroadcast) (1 per 10 seconds) and [Transactional](#sendEmail) (100 per second) endpoints, requests are limited to 10 per second.


    # Use our Postman collection


    We''ve generated a Postman collection to help you get started with our APIs.


    If you fork this collection, you might want to disable the *Watch original collection* option. We automatically update our Postman collection whenever we release changes to our documentation, even if we don''t change our APIs—which happens daily! Rather than being flooded with Postman notifications, you can check out our [Release Notes](/release-notes/) for updates to our APIs.


    **NOTE**: Postman endpoints default to our US APIs. If you''re in our European (EU) region, you''ll need to add `-eu` to the server variables (`track_api_url` and `app_api_url`).


    [<img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;">](https://god.gw.postman.com/run-collection/23697545-2931c004-e63d-4cdc-bf4b-e685ba6da42d?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D23697545-2931c004-e63d-4cdc-bf4b-e685ba6da42d%26entityType%3Dcollection%26workspaceId%3Db886877f-fc09-475f-84fe-6221a98f4d18#?env%5BCustomer.io%20API%20Environment%5D=W3sia2V5IjoidHJhY2tfYXBpX3VybCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiJ0cmFjay5jdXN0b21lci5pbyIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBwX2FwaV91cmwiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiYXBpLmN1c3RvbWVyLmlvIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzaXRlX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYXBpX2tleSIsInR5cGUiOiJzZWNyZXQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYmVhcmVyIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYnJvYWRjYXN0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaW1wb3J0X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiZW1haWxfYWRkcmVzcyIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InN1cHByZXNzaW9uX3R5cGUiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjb2xsZWN0aW9uX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoic25pcHBldF9uYW1lIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5Ijoid2ViaG9va19pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InNlbmRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImV4cG9ydF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6Im1lc3NhZ2VfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJzZWdtZW50X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoibmV3c2xldHRlcl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImNvbnRlbnRfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJjYW1wYWlnbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFjdGlvbl9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImN1c3RvbWVyX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidHJhbnNhY3Rpb25hbF9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRyaWdnZXJfaWQiLCJ0eXBlIjoiZGVmYXVsdCIsInZhbHVlIjoiIiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJmb3JtX2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiaWRlbnRpZmllciIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRldmljZV9pZCIsInR5cGUiOiJkZWZhdWx0IiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImRlbGl2ZXJ5X2lkIiwidHlwZSI6ImRlZmF1bHQiLCJ2YWx1ZSI6IiIsImVuYWJsZWQiOnRydWV9XQ==)


    # Server addresses: US and EU


    Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.


    | Region | Server Address |

    | :-- | :-- |

    | US | https://api.customer.io |

    | EU | https://api-eu.customer.io |


    # Authentication


    All requests to the Customer.io App API use an [App API Key](#App-API-Key).


    To authenticate, provide your key as a Bearer token in a HTTP Authorization header. You can create and manage your API keys—including keys with different scopes—in [your account settings page](https://fly.customer.io/settings/api_credentials?keyType=app). Each operation on this page references the authorization header it requires.


    # Rate Limits


    Most endpoints on this page are limited to 10 requests per second. The exceptions are:

    * The [transactional email](#operation/sendEmail) endpoint is limited to 100 requests per second.

    * The [API-triggered broadcast endpoint](#operation/triggerBroadcast) is limited to 1 request every 10 seconds.


    **Rate limits are subject to change. We may adjust these thresholds to ensure stable performance for all customers.**

    '
servers:
- url: https://api.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Live Notifications
  description: 'Start, update, and end live notifications—real-time activities on the iOS Lock Screen and Dynamic Island, and in the Android notification shade. Your server drives the activity''s content; Customer.io handles token lookup and push delivery.

    '
paths:
  /v1/live_notifications/start:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    post:
      summary: Start a live notification
      operationId: startLiveNotification
      security:
      - Bearer-Auth: []
      description: '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/push/live-activities/#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.

        '
      tags:
      - Live Notifications
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - identifiers
              - notification_type
              - attributes
              - content_state
              properties:
                identifiers:
                  type: object
                  description: 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.
                  properties:
                    id:
                      type: string
                      description: The profile's `id` attribute.
                    email:
                      type: string
                      description: The profile's email address.
                    phone:
                      type: string
                      description: The profile's phone number.
                    internal:
                      type: string
                      description: Our internal identifier for the profile, prefixed with `cio_`.
                notification_type:
                  type: string
                  description: 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:
                  type: string
                  description: The device token identifying the device to start the activity on.
                platform:
                  type: string
                  enum:
                  - ios
                  - android
                  description: The device platform.
                app_identifier:
                  type: string
                  description: '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:
                  minProperties: 1
                  description: Static fields set once at start. They can't change after you start the activity. The attributes' shape depends on your `notification_type`. For iOS or a free form Android activity, pick the free form variant. For other Android notification types, pick the matching variant below. See the [payload reference](/messaging/channels/live-notifications/payload-reference/) for details.
                  anyOf:
                  - x-scalar-ignore: true
                    title: Free-form (iOS or Android custom type)
                    type: object
                    description: 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.
                    additionalProperties: true
                  - x-scalar-ignore: true
                    title: Multi-step tracker
                    type: object
                    description: 'Static fields for a multi-step tracker template. `notification_type`: `io.customer.livenotifications.segments`.'
                    required:
                    - header
                    properties:
                      header:
                        type: string
                        description: Top-row label
                  - x-scalar-ignore: true
                    title: Countdown timer
                    type: object
                    description: 'Static fields for the countdown timer template. `notification_type`: `io.customer.livenotifications.countdowntimer`.'
                    required:
                    - header
                    properties:
                      header:
                        type: string
                        description: Top-row label of the notification.
                content_state:
                  minProperties: 1
                  description: 'The initial dynamic content for the activity. [The shape depends on your `notification_type`](/messaging/channels/live-notifications/payload-reference/#android-built-in-template-fields)—pick the matching variant below. Date fields are epoch seconds.

                    '
                  anyOf:
                  - x-scalar-ignore: true
                    title: Free-form (iOS or Android custom type)
                    type: object
                    description: 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.
                    additionalProperties: true
                  - x-scalar-ignore: true
                    title: Multi-step tracker
                    type: object
                    description: 'Dynamic fields for the multi-step tracker template. `notification_type`: `io.customer.livenotifications.segments`.'
                    required:
                    - status
                    - segmentsTotal
                    - segmentsComplete
                    properties:
                      status:
                        type: string
                        description: Primary status line, like `Out for delivery`.
                      substatus:
                        type: string
                        description: Secondary line under the status.
                      segmentsTotal:
                        type: integer
                        minimum: 1
                        maximum: 20
                        description: The total number of segments in the progress bar. Values above 20 are capped at 20.
                      segmentsComplete:
                        type: integer
                        description: How many segments are filled; the remainder render as incomplete. Values above segmentsTotal are capped at segmentsTotal.
                      trailingText:
                        type: string
                        description: Short text on the Dynamic Island trailing edge, e.g. \"5 min\". Keep it brief; the trailing region is narrow.
                  - x-scalar-ignore: true
                    title: Countdown timer
                    type: object
                    description: 'Dynamic fields for the countdown timer template. `notification_type`: `io.customer.livenotifications.countdowntimer`.'
                    required:
                    - title
                    properties:
                      title:
                        type: string
                        description: Primary status line.
                      statusMessage:
                        type: string
                        description: Secondary line under the title.
                      endTime:
                        type: integer
                        description: 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:
                  type: object
                  description: The alert shown when the activity starts. Required for iOS.
                  properties:
                    alert:
                      type: object
                      required:
                      - title
                      - body
                      properties:
                        title:
                          type: string
                          description: The alert title.
                        body:
                          type: string
                          description: The alert body.
                        sound:
                          type: string
                          description: The sound to play when the activity starts.
                deep_link:
                  type: string
                  description: A link to open when the person taps the activity.
                expiration:
                  type: integer
                  description: '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.

                    '
      responses:
        '200':
          description: The activity was queued. Returns the instance ID for the new activity.
          content:
            application/json:
              schema:
                type: object
                properties:
                  instance_id:
                    type: string
                    description: The unique identifier (ULID) for the new activity instance. Use it to update, end, or check the status of the activity.
        '400':
          description: The request was malformed—a missing required field, an invalid platform, more or fewer than one identifier, or a missing iOS alert.
        '404':
          description: Live notifications aren't enabled for this workspace.
      x-codeSamples:
      - lang: json
        label: JSON
        source: "{\n  \"identifiers\": {},\n  \"notification_type\": \"string\",\n  \"attributes\": {},\n  \"content_state\": {}\n}"
      - lang: Shell + Curl
        source: "curl --request POST \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/live_notifications/start \\\n  --header 'content-type: application/json' \\\n  --data '{\"identifiers\":{\"id\":\"string\",\"email\":\"string\",\"phone\":\"string\",\"internal\":\"string\"},\"notification_type\":\"string\",\"device_id\":\"string\",\"platform\":\"ios\",\"app_identifier\":\"string\",\"attributes\":{},\"content_state\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\",\"expiration\":0}'"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"POST\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/live_notifications/start\",\n  \"headers\": {\n    \"content-type\": \"application/json\"\n  }\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.write(JSON.stringify({\n  identifiers: {id: 'string', email: 'string', phone: 'string', internal: 'string'},\n  notification_type: 'string',\n  device_id: 'string',\n  platform: 'ios',\n  app_identifier: 'string',\n  attributes: {},\n  content_state: {},\n  push_payload: {alert: {title: 'string', body: 'string', sound: 'string'}},\n  deep_link: 'string',\n  expiration: 0\n}));\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/live_notifications/start")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Post.new(url)

          request["content-type"] = ''application/json''

          request.body = "{\"identifiers\":{\"id\":\"string\",\"email\":\"string\",\"phone\":\"string\",\"internal\":\"string\"},\"notification_type\":\"string\",\"device_id\":\"string\",\"platform\":\"ios\",\"app_identifier\":\"string\",\"attributes\":{},\"content_state\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\",\"expiration\":0}"


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          payload = "{\"identifiers\":{\"id\":\"string\",\"email\":\"string\",\"phone\":\"string\",\"internal\":\"string\"},\"notification_type\":\"string\",\"device_id\":\"string\",\"platform\":\"ios\",\"app_identifier\":\"string\",\"attributes\":{},\"content_state\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\",\"expiration\":0}"


          headers = { ''content-type'': "application/json" }


          conn.request("POST", "/v1/live_notifications/start", payload, headers)


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/live_notifications/start\"\n\n\tpayload := strings.NewReader(\"{\\\"identifiers\\\":{\\\"id\\\":\\\"string\\\",\\\"email\\\":\\\"string\\\",\\\"phone\\\":\\\"string\\\",\\\"internal\\\":\\\"string\\\"},\\\"notification_type\\\":\\\"string\\\",\\\"device_id\\\":\\\"string\\\",\\\"platform\\\":\\\"ios\\\",\\\"app_identifier\\\":\\\"string\\\",\\\"attributes\\\":{},\\\"content_state\\\":{},\\\"push_payload\\\":{\\\"alert\\\":{\\\"title\\\":\\\"string\\\",\\\"body\\\":\\\"string\\\",\\\"sound\\\":\\\"string\\\"}},\\\"deep_link\\\":\\\"string\\\",\\\"expiration\\\":0}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"content-type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
  /v1/live_notifications/update:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    post:
      summary: Update a live notification
      operationId: updateLiveNotification
      security:
      - Bearer-Auth: []
      description: 'Push a new content state to a running activity, referenced by its `instance_id`. The device re-renders the activity from the state you send.


        Send the **full** content state on every update, not just the fields that changed—the platforms don''t support partial updates.


        `push_payload` is optional on updates, whether Customer.io delivers directly through APNs or relays through Firebase Cloud Messaging (FCM). If you include a `push_payload.alert`, it must contain both a `title` and a `body`.

        '
      tags:
      - Live Notifications
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - instance_id
              - content_state
              properties:
                instance_id:
                  type: string
                  description: The activity's instance ID (ULID), returned when you started it.
                content_state:
                  minProperties: 1
                  description: The complete new content state for the activity. The content state's shape depends on the activity's `notification_type`. For iOS or a free form Android activity, pick the free form variant. For other Android notification types, pick the matching variant below. Date fields are epoch seconds.
                  anyOf:
                  - x-scalar-ignore: true
                    title: Free-form (iOS or Android custom type)
                    type: object
                    description: 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.
                    additionalProperties: true
                  - x-scalar-ignore: true
                    title: Multi-step tracker
                    type: object
                    description: 'Dynamic fields for the multi-step tracker template. `notification_type`: `io.customer.livenotifications.segments`.'
                    required:
                    - status
                    - segmentsTotal
                    - segmentsComplete
                    properties:
                      status:
                        type: string
                        description: Primary status line, like `Out for delivery`.
                      substatus:
                        type: string
                        description: Secondary line under the status.
                      segmentsTotal:
                        type: integer
                        minimum: 1
                        maximum: 20
                        description: The total number of segments in the progress bar. Values above 20 are capped at 20.
                      segmentsComplete:
                        type: integer
                        description: How many segments are filled; the remainder render as incomplete. Values above segmentsTotal are capped at segmentsTotal.
                      trailingText:
                        type: string
                        description: Short text on the Dynamic Island trailing edge, e.g. \"5 min\". Keep it brief; the trailing region is narrow.
                  - x-scalar-ignore: true
                    title: Countdown timer
                    type: object
                    description: 'Dynamic fields for the countdown timer template. `notification_type`: `io.customer.livenotifications.countdowntimer`.'
                    required:
                    - title
                    properties:
                      title:
                        type: string
                        description: Primary status line.
                      statusMessage:
                        type: string
                        description: Secondary line under the title.
                      endTime:
                        type: integer
                        description: 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.
                attributes:
                  type: object
                  description: Static activity fields, for renderers that need them alongside the content state. On iOS, attributes can't change after start.
                  additionalProperties: true
                push_payload:
                  type: object
                  description: The alert to accompany the update. Optional whether Customer.io delivers directly through APNs or relays through Firebase Cloud Messaging (FCM). If you include an alert, provide both its `title` and `body`.
                  properties:
                    alert:
                      type: object
                      required:
                      - title
                      - body
                      properties:
                        title:
                          type: string
                          description: The alert title.
                        body:
                          type: string
                          description: The alert body.
                        sound:
                          type: string
                          description: The sound to play with the update.
                deep_link:
                  type: string
                  description: A link to open when the person taps the activity.
      responses:
        '200':
          description: The update was queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  instance_id:
                    type: string
                    description: The activity's instance ID.
        '400':
          description: The request was malformed, `instance_id` isn't a valid ULID, or a `push_payload.alert` was missing a `title` or `body`.
        '404':
          description: Live notifications aren't enabled for this workspace.
      x-codeSamples:
      - lang: json
        label: JSON
        source: "{\n  \"instance_id\": \"string\",\n  \"content_state\": {}\n}"
      - lang: Shell + Curl
        source: "curl --request POST \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/live_notifications/update \\\n  --header 'content-type: application/json' \\\n  --data '{\"instance_id\":\"string\",\"content_state\":{},\"attributes\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\"}'"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"POST\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/live_notifications/update\",\n  \"headers\": {\n    \"content-type\": \"application/json\"\n  }\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.write(JSON.stringify({\n  instance_id: 'string',\n  content_state: {},\n  attributes: {},\n  push_payload: {alert: {title: 'string', body: 'string', sound: 'string'}},\n  deep_link: 'string'\n}));\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/live_notifications/update")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Post.new(url)

          request["content-type"] = ''application/json''

          request.body = "{\"instance_id\":\"string\",\"content_state\":{},\"attributes\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\"}"


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          payload = "{\"instance_id\":\"string\",\"content_state\":{},\"attributes\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\"}"


          headers = { ''content-type'': "application/json" }


          conn.request("POST", "/v1/live_notifications/update", payload, headers)


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/live_notifications/update\"\n\n\tpayload := strings.NewReader(\"{\\\"instance_id\\\":\\\"string\\\",\\\"content_state\\\":{},\\\"attributes\\\":{},\\\"push_payload\\\":{\\\"alert\\\":{\\\"title\\\":\\\"string\\\",\\\"body\\\":\\\"string\\\",\\\"sound\\\":\\\"string\\\"}},\\\"deep_link\\\":\\\"string\\\"}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"content-type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
  /v1/live_notifications/end:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    post:
      summary: End a live notification
      operationId: endLiveNotification
      security:
      - Bearer-Auth: []
      description: 'End a running activity, referenced by its `instance_id`. On iOS, the system dismisses the activity from the Lock Screen. On Android, the SDK normally renders the final content as a non-ongoing notification; it cancels the notification only when there''s no final notification to render. You can include a final `content_state` to show before the activity ends.


        `push_payload` is optional on the end call, whether Customer.io delivers directly through APNs or relays through Firebase Cloud Messaging (FCM). If you include a `push_payload.alert`, it must contain both a `title` and a `body`.

        '
      tags:
      - Live Notifications
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - instance_id
              properties:
                instance_id:
                  type: string
                  description: The activity's instance ID (ULID), returned when you started it.
                content_state:
                  description: The final content state to show before the activity ends. Defaults to the last state you sent. The content state's shape depends on the activity's `notification_type`. For iOS or a free form Android activity, pick the free form variant. For other Android notification types, pick the matching variant below.
                  anyOf:
                  - x-scalar-ignore: true
                    title: Free-form (iOS or Android custom type)
                    type: object
                    description: 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.
                    additionalProperties: true
                  - x-scalar-ignore: true
                    title: Multi-step tracker
                    type: object
                    description: 'Dynamic fields for the multi-step tracker template. `notification_type`: `io.customer.livenotifications.segments`.'
                    required:
                    - status
                    - segmentsTotal
                    - segmentsComplete
                    properties:
                      status:
                        type: string
                        description: Primary status line, like `Out for delivery`.
                      substatus:
                        type: string
                        description: Secondary line under the status.
                      segmentsTotal:
                        type: integer
                        minimum: 1
                        maximum: 20
                        description: The total number of segments in the progress bar. Values above 20 are capped at 20.
                      segmentsComplete:
                        type: integer
                        description: How many segments are filled; the remainder render as incomplete. Values above segmentsTotal are capped at segmentsTotal.
                      trailingText:
                        type: string
                        description: Short text on the Dynamic Island trailing edge, e.g. \"5 min\". Keep it brief; the trailing region is narrow.
                  - x-scalar-ignore: true
                    title: Countdown timer
                    type: object
                    description: 'Dynamic fields for the countdown timer template. `notification_type`: `io.customer.livenotifications.countdowntimer`.'
                    required:
                    - title
                    properties:
                      title:
                        type: string
                        description: Primary status line.
                      statusMessage:
                        type: string
                        description: Secondary line under the title.
                      endTime:
                        type: integer
                        description: 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.
                attributes:
                  type: object
                  description: Static activity fields, for renderers that need them alongside the content state.
                  additionalProperties: true
                push_payload:
                  type: object
                  description: The alert to accompany the end event. Optional whether Customer.io delivers directly through APNs or relays through Firebase Cloud Messaging (FCM). If you include an alert, provide both its `title` and `body`.
                  properties:
                    alert:
                      type: object
                      required:
                      - title
                      - body
                      properties:
                        title:
                          type: string
                          description: The alert title.
                        body:
                          type: string
                          description: The alert body.
                        sound:
                          type: string
                          description: The sound to play with the end event.
                deep_link:
                  type: string
                  description: A link to open when the person taps the activity.
      responses:
        '200':
          description: The end event was queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  instance_id:
                    type: string
                    description: The activity's instance ID.
        '400':
          description: The request was malformed, `instance_id` isn't a valid ULID, or a `push_payload.alert` was missing a `title` or `body`.
        '404':
          description: Live notifications aren't enabled for this workspace.
      x-codeSamples:
      - lang: json
        label: JSON
        source: "{\n  \"instance_id\": \"string\"\n}"
      - lang: Shell + Curl
        source: "curl --request POST \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/live_notifications/end \\\n  --header 'content-type: application/json' \\\n  --data '{\"instance_id\":\"string\",\"content_state\":{},\"attributes\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\"}'"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"POST\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/live_notifications/end\",\n  \"headers\": {\n    \"content-type\": \"application/json\"\n  }\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.write(JSON.stringify({\n  instance_id: 'string',\n  content_state: {},\n  attributes: {},\n  push_payload: {alert: {title: 'string', body: 'string', sound: 'string'}},\n  deep_link: 'string'\n}));\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/live_notifications/end")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Post.new(url)

          request["content-type"] = ''application/json''

          request.body = "{\"instance_id\":\"string\",\"content_state\":{},\"attributes\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\"}"


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          payload = "{\"instance_id\":\"string\",\"content_state\":{},\"attributes\":{},\"push_payload\":{\"alert\":{\"title\":\"string\",\"body\":\"string\",\"sound\":\"string\"}},\"deep_link\":\"string\"}"


          headers = { ''content-type'': "application/json" }


          conn.request("POST", "/v1/live_notifications/end", payload, headers)


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/live_notifications/end\"\n\n\tpayload := strings.NewReader(\"{\\\"instance_id\\\":\\\"string\\\",\\\"content_state\\\":{},\\\"attributes\\\":{},\\\"push_payload\\\":{\\\"alert\\\":{\\\"title\\\":\\\"string\\\",\\\"body\\\":\\\"string\\\",\\\"sound\\\":\\\"string\\\"}},\\\"deep_link\\\":\\\"string\\\"}\")\n\n\treq, _ := http.NewRequest(\"POST\", url, payload)\n\n\treq.Header.Add(\"content-type\", \"application/json\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
  /v1/live_notifications/{instance_id}:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    get:
      summary: Get a live notification's status
      operationId: getLiveNotification
      security:
      - Bearer-Auth: []
      description: 'Look up a live notification''s current state, lifecycle timestamps, and the status of its most recent delivery.

        '
      tags:
      - Live Notifications
      parameters:
      - name: instance_id
        in: path
        required: true
        schema:
          type: string
        description: The activity's instance ID (ULID), returned when you started it.
      responses:
        '200':
          description: The activity's current status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  instance_id:
                    type: string
                    description: The activity's instance ID.
                  notification_type:
                    type: string
                    description: The activity's reverse-DNS type identifier.
                  platform:
                    type: string
                    description: The device platform—`ios` or `android`.
                  state:
                    type: string
                    enum:
                    - active
                    - ended
                    - expired
                    - failed
                    description: The activity's lifecycle state.
                  failure_reason:
                    type: string
                    nullable: true
                    description: Why the activity failed, when `state` is `failed`.
                  started_at:
                    type: integer
                    description: When the activity started (unix timestamp).
                  ended_at:
                    type: integer
                    nullable: true
                    description: When the activity ended (unix timestamp).
                  expires_at:
                    type: integer
                    nullable: true
                    description: When the activity expires (unix timestamp).
                  last_delivery:
                    type: object
                    nullable: true
                    description: The most recent delivery for the activity.
                    properties:
                      id:
                        type: string
                        description: The delivery ID.
                      operation:
                        type: string
                        enum:
                        - start
                        - update
                        - end
                        description: The lifecycle operation the delivery carried.
                      status:
                        type: string
                        enum:
                        - queued
                        - sent
                        - failed
                        - undeliverable
                        description: The delivery's status.
                      source:
                        type: string
                        description: Where the operation originated—the API or the device.
                      created_at:
                        type: integer
                        description: When the delivery was created (unix timestamp).
        '400':
          description: '`instance_id` isn''t a valid ULID.'
        '404':
          description: The activity wasn't found—a recently started one may not be processed yet—or live notifications aren't enabled for this workspace.
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request GET \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/live_notifications/{instance_id}"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"GET\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/live_notifications/%7Binstance_id%7D\",\n  \"headers\": {}\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/live_notifications/%7Binstance_id%7D")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Get.new(url)


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          conn.request("GET", "/v1/live_notifications/%7Binstance_id%7D")


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/live_notifications/%7Binstance_id%7D\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
components:
  securitySchemes:
    Bearer-Auth:
      type: http
      scheme: bearer
      description: 'The App API uses a bearer authentication scheme.


        You can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).

        '
    ServiceAccount-Auth:
      x-scalar-ignore: true
      type: http
      scheme: bearer
      bearerFormat: sa_live_
      description: 'Transactional send endpoints (`/v1/send/email`, `/v1/send/push`, `/v1/send/sms`, `/v1/send/in_app`, `/v1/send/inbox_message`) also accept a service-account bearer token, prefixed with `sa_live_`. Service-account tokens work across workspaces, so you must pass the target workspace as the `X-Workspace-Id` header on each request.


        Service-account tokens are intended for testing and one-off sends—for example, using the Customer.io CLI with an AI agent like Claude to verify that a transactional message renders correctly before wiring it into your production backend. **For the production integration that triggers the message from your application, use an App API Key instead**: it''s workspace-scoped, easier to rotate, and has a smaller blast radius.


        Service-account tokens are server-side credentials. Treat them like any API key—keep them in environment variables or a secret manager, and never embed them in client-side code, mobile apps, or other untrusted contexts.

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token