OneSignal Users & Subscriptions API

openapi: 3.0.0
info:
  contact:
    email: [email protected]
    name: OneSignal DevRel
    url: https://onesignal.com
  description: A powerful way to send personalized messages at scale and build effective
    customer engagement strategies. Learn more at onesignal.com
  termsOfService: https://onesignal.com/tos
  title: OneSignal
  version: 5.5.0
servers:
- url: https://api.onesignal.com
paths:
  /notifications:
    get:
      description: View the details of multiple notifications
      operationId: get_notifications
      parameters:
      - description: The app ID that you want to view notifications from
        explode: true
        in: query
        name: app_id
        required: true
        schema:
          type: string
        style: form
      - description: How many notifications to return.  Max is 50.  Default is 50.
        explode: true
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      - description: Page offset.  Default is 0.  Results are sorted by queued_at
          in descending order.  queued_at is a representation of the time that the
          notification was queued at.
        explode: true
        in: query
        name: offset
        required: false
        schema:
          type: integer
        style: form
      - description: |
          Kind of notifications returned:
            * unset - All notification types (default)
            * `0` - Dashboard only
            * `1` - API only
            * `3` - Automated only
        explode: true
        in: query
        name: kind
        required: false
        schema:
          enum:
          - 0
          - 1
          - 3
          type: integer
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSlice'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: View notifications
    post:
      description: "Sends notifications to your users.\n\n**Target by External ID\
        \ (push example):** set `include_aliases` to `{ \"external_id\": [\"your-user-id\"\
        ] }` and set `target_channel` to `push` (or `email` / `sms` for those channels).\
        \ Alias object keys must match API labels exactly (for example `external_id`,\
        \ not camelCase).\n\n**Do not confuse** the notification-level `external_id`\
        \ field with External ID targeting: top-level `external_id` / `idempotency_key`\
        \ are for idempotent notification requests only, not for selecting recipients.\n\
        \n**Targeting compatibility:** `include_aliases` must not be combined with\
        \ other targeting modes (segments, filters, subscription IDs, legacy player\
        \ IDs, etc.). Clients should send only one targeting strategy per request.\n"
      operationId: create_notification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Notification'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateNotificationSuccessResponse'
          description: "OK, invalid_aliases, or No Subscribed Players\nIf a message\
            \ was successfully created, you will get a 200 response with a non-empty\
            \ `id` for the notification.\nIf the 200 response contains `invalid_aliases`,\
            \ that marks devices that exist in the provided app_id but are no longer\
            \ subscribed.\nIf `id` is an empty string, no notification was created:\
            \ check the `errors` array (for example messages such as \"All included\
            \ players are not subscribed\") even though HTTP status is still 200.\
            \ This can happen when alias keys are wrong, External IDs do not resolve\
            \ to subscribed users, or other validation issues.\nIf no id is returned,\
            \ then a message was not created and the targeted User IDs do not exist\
            \ under the provided app_id.\nAny User IDs sent in the request that do\
            \ not exist under the specified app_id will be ignored.\n"
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Create notification
      x-onesignal-flat-notification-example: true
  /notifications/{notification_id}:
    delete:
      description: Used to stop a scheduled or currently outgoing notification
      operationId: cancel_notification
      parameters:
      - explode: true
        in: query
        name: app_id
        required: true
        schema:
          type: string
        style: form
      - explode: false
        in: path
        name: notification_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessBoolResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Stop a scheduled or currently outgoing notification
    get:
      description: View the details of a single notification and outcomes associated
        with it
      operationId: get_notification
      parameters:
      - explode: true
        in: query
        name: app_id
        required: true
        schema:
          type: string
        style: form
      - explode: false
        in: path
        name: notification_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationWithMeta'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: View notification
  /notifications/{notification_id}/history:
    post:
      description: "-> View the devices sent a message - OneSignal Paid Plan Required\
        \ This method will return all devices that were sent the given notification_id\
        \ of an Email or Push Notification if used within 7 days of the date sent.\
        \ After 7 days of the sending date, the message history data will be unavailable.\
        \ After a successful response is received, the destination url may be polled\
        \ until the file becomes available. Most exports are done in ~1-3 minutes,\
        \ so setting a poll interval of 10 seconds should be adequate. For use cases\
        \ that are not meant to be consumed by a script, an email will be sent to\
        \ the supplied email address. 🚧 Requirements A OneSignal Paid Plan.\
        \ Turn on Send History via OneSignal API in Settings -> Analytics. Cannot\
        \ get data before this was turned on. Must be called within 7 days after sending\
        \ the message. Messages targeting under 1000 recipients will not have \"sent\"\
        \ events recorded, but will show \"clicked\" events. Requires your OneSignal\
        \ App's REST API Key, available in Keys & IDs."
      operationId: get_notification_history
      parameters:
      - description: The "id" of the message found in the Notification object
        explode: false
        in: path
        name: notification_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        $ref: '#/components/requestBodies/get_notification_history_request_body'
        content:
          application/json:
            schema:
              properties:
                events:
                  description: "-> \"sent\" - All the devices by player_id that were\
                    \ sent the specified notification_id.  Notifications targeting\
                    \ under 1000 recipients will not have \"sent\" events recorded,\
                    \ but will show \"clicked\" events. \"clicked\" - All the devices\
                    \ by `player_id` that clicked the specified notification_id."
                  enum:
                  - sent
                  - clicked
                  type: string
                email:
                  description: The email address you would like the report sent.
                  type: string
                app_id:
                  type: string
              required:
              - id
              title: get_notification_history_request_body
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationHistorySuccessResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Notification History
  /apps:
    get:
      description: View the details of all of your current OneSignal apps
      operationId: get_apps
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Apps'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - organization_api_key: []
      summary: View apps
    post:
      description: Creates a new OneSignal app
      operationId: create_app
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/App'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - organization_api_key: []
      summary: Create an app
  /apps/{app_id}:
    get:
      description: View the details of a single OneSignal app
      operationId: get_app
      parameters:
      - description: An app id
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - organization_api_key: []
      summary: View an app
    put:
      description: Updates the name or configuration settings of an existing OneSignal
        app
      operationId: update_app
      parameters:
      - description: An app id
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/App'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - organization_api_key: []
      summary: Update an app
  /apps/{app_id}/segments:
    get:
      description: Returns an array of segments from an app.
      operationId: get_segments
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: "Segments are listed in ascending order of created_at date. offset\
          \ will omit that number of segments from the beginning of the list. Eg offset\
          \ 5, will remove the 5 earliest created Segments."
        explode: true
        in: query
        name: offset
        required: false
        schema:
          type: integer
        style: form
      - description: The amount of Segments in the response. Maximum 300.
        explode: true
        in: query
        name: limit
        required: false
        schema:
          type: integer
        style: form
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSegmentsSuccessResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Get Segments
    post:
      description: "Create a segment visible and usable in the dashboard and API -\
        \ Required: OneSignal Paid Plan\nThe Create Segment method is used when you\
        \ want your server to programmatically create a segment instead of using the\
        \ OneSignal Dashboard UI. Just like creating Segments from the dashboard you\
        \ can pass in filters with multiple \"AND\" or \"OR\" operator's.\n🚧\n\
        Does Not Update Segments\nThis endpoint will only create segments, it does\
        \ not edit or update currently created Segments. You will need to use the\
        \ Delete Segment endpoint and re-create it with this endpoint to edit.\n"
      operationId: create_segment
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Segment'
        required: false
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSegmentSuccessResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSegmentConflictResponse'
          description: Conflict
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Create Segment
  /apps/{app_id}/segments/{segment_id}:
    delete:
      description: "Delete a segment (not user devices) - Required: OneSignal Paid\
        \ Plan\nYou can delete a segment under your app by calling this API. You must\
        \ provide an API key in the Authorization header that has admin access on\
        \ the app.\nThe segment_id can be found in the URL of the segment when viewing\
        \ it in the dashboard.\n"
      operationId: delete_segment
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: The segment_id can be found in the URL of the segment when viewing
          it in the dashboard.
        explode: false
        in: path
        name: segment_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessBoolResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccessBoolResponse'
          description: Not Found
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Delete Segment
  /apps/{app_id}/outcomes:
    get:
      description: "View the details of all the outcomes associated with your app\n\
        \n🚧\nRequires Authentication Key\nRequires your OneSignal App's REST\
        \ API Key, available in Keys & IDs.\n\n🚧\nOutcome Data Limitations\n\
        Outcomes are only accessible for around 30 days before deleted from our servers.\
        \ You will need to export this data every month if you want to keep it.\n"
      operationId: get_outcomes
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: "Required\nComma-separated list of names and the value (sum/count)\
          \ for the returned outcome data.\nNote: Clicks only support count aggregation.\n\
          For out-of-the-box OneSignal outcomes such as click and session duration,\
          \ please use the \"os\" prefix with two underscores. For other outcomes,\
          \ please use the name specified by the user.\nExample:os__session_duration.count,os__click.count,CustomOutcomeName.sum\n"
        explode: true
        in: query
        name: outcome_names
        required: true
        schema:
          type: string
        style: form
      - description: "Optional\nIf outcome names contain any commas, then please specify\
          \ only one value at a time.\nExample: outcome_names[]=os__click.count&outcome_names[]=Sales,\
          \ Purchase.count\nwhere \"Sales, Purchase\" is the custom outcomes with\
          \ a comma in the name.\n"
        explode: true
        in: query
        name: "outcome_names[]"
        required: false
        schema:
          type: string
        style: form
      - description: "Optional\nTime range for the returned data. The values can be\
          \ 1h (for the last 1 hour data), 1d (for the last 1 day data), or 1mo (for\
          \ the last 1 month data).\nDefault is 1h if the parameter is omitted.\n"
        explode: true
        in: query
        name: outcome_time_range
        required: false
        schema:
          type: string
        style: form
      - description: "Optional\nPlatform id. Refer device's platform ids for values.\n\
          Example:\noutcome_platform=0 for iOS\noutcome_platform=7,8 for Safari and\
          \ Firefox\nDefault is data from all platforms if the parameter is omitted.\n"
        explode: true
        in: query
        name: outcome_platforms
        required: false
        schema:
          type: string
        style: form
      - description: "Optional\nAttribution type for the outcomes. The values can\
          \ be direct or influenced or unattributed.\nExample: outcome_attribution=direct\n\
          Default is total (returns direct+influenced+unattributed) if the parameter\
          \ is omitted.\n"
        explode: true
        in: query
        name: outcome_attribution
        required: false
        schema:
          type: string
        style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutcomesData'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: View Outcomes
  /apps/{app_id}/activities/activity/{activity_type}:
    post:
      description: Remotely start a Live Activity on iOS devices via OneSignal’s REST
        API.
      operationId: start_live_activity
      parameters:
      - description: Your OneSignal App ID in UUID v4 format.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: The name of the Live Activity defined in your app. This should
          match the attributes struct used in your app's Live Activity implementation.
        explode: false
        in: path
        name: activity_type
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartLiveActivityRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartLiveActivitySuccessResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Start Live Activity
  /apps/{app_id}/live_activities/{activity_id}/notifications:
    post:
      description: Updates a specified live activity.
      operationId: update_live_activity
      parameters:
      - description: The OneSignal App ID for your app.  Available in Keys & IDs.
        explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - description: Live Activity record ID
        explode: false
        in: path
        name: activity_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLiveActivityRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLiveActivitySuccessResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
      summary: Update a Live Activity via Push
  /apps/{app_id}/users:
    post:
      description: "Creates a User, optionally Subscriptions owned by the User as\
        \ well as Aliases.\nAliases provided in the payload will be used to look up\
        \ an existing User."
      operationId: create_user
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: CREATED
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: CREATED
        "202":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: ACCEPTED
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserConflictResponse'
          description: Multiple User Identity Conflict
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
  /apps/{app_id}/users/by/{alias_label}/{alias_id}:
    delete:
      description: "Removes the User identified by (:alias_label, :alias_id), and\
        \ all Subscriptions and Aliases"
      operationId: delete_user
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Conflict
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
    get:
      description: "Returns the User’s properties, Aliases, and Subscriptions."
      operationId: get_user
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Not Found
        "429":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
          description: Rate Limit Exceeded
      security:
      - rest_api_key: []
    patch:
      description: Updates an existing User’s properties.
      operationId: update_user
      parameters:
      - explode: false
        in: path
        name: app_id
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_label
        required: true
        schema:
          type: string
        style: simple
      - explode: false
        in: path
        name: alias_id
        required: true
        schema:
          type: string
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
        required: true
      responses:
        "202":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertiesBody'
          description: ACCEPTED
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Bad Request
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericError'
          description: Conflict
        "429":
          content:
            application/json:
           

# --- truncated at 32 KB (181 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/onesignal/refs/heads/main/openapi/onesignal-openapi.yml