View the details of a single notification and outcomes associated with it

🚧

Requires Authentication Key

Requires your OneSignal App's REST API Key, available in Keys & IDs.

Path Parameters

Parameter

Type

Description

id

String

Required: Notification ID

app_id

String

Required: App ID

For notification-specific outcomes data:

Parameter

Type

Description

outcome_names

String

Optional:
Comma-separated list of names and the value (sum/count) for the returned outcome data.
Note: Clicks only support count aggregation.

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.

Example:os__session_duration.count,os__click.count,CustomOutcomeName.sum

Note: If the outcome_names parameter is omitted, then no outcomes data will be returned and all the other outcomes-specific parameters listed below will be ignored.

outcome_names[]
(if outcome names have commas in them)

String

Optional:
If outcome names contain any commas, then please specify only one value at a time.

Example: outcome_names[]=os__click.count&outcome_names[]=Sales, Purchase.count
where “Sales, Purchase” is the custom outcomes with a comma in the name.

outcome_time_range

String

Optional:
Time 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).

Default is 1h if the parameter is omitted.

This parameter is ignored if outcome_names parameter is not specified.

outcome_platforms

String

Optional:
Platform id. Refer device's platform ids for values.

Example:
outcome_platforms=0 for iOS
outcome_platforms=7,8 for Safari and Firefox

Default is data from all platforms if the parameter is omitted.

This parameter is ignored if outcome_names parameter is not specified.

outcome_attribution

String

Optional:
Attribution type for the outcomes. The values can be direct or influenced

Example: outcome_attribution=direct

Default is total (returns direct+influenced) if the parameter is omitted.

This parameter is ignored if outcome_names parameter is not specified.

Example Code - View notification

curl --include \
     --header "Authorization: Basic YOUR_REST_API_KEY" \
 https://onesignal.com/api/v1/notifications/THE_NOTIFICATION_ID?app_id=YOUR_APP_ID
<?PHP
        $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://onesignal.com/api/v1/notifications/YOUR_NOTIFICATION_ID?app_id=YOUR_APP_ID");
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
                           'Authorization: Basic AUTH_KEY'));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_HEADER, FALSE);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

    $response = curl_exec($ch);
    curl_close($ch);
        $return["allresponses"] = $response;
    $return = json_encode( $return);
  
      print("\n\nJSON received:\n");
      print($return);
      print("\n");
?>

Example Code for outcomes data

curl --include \
    --header "Authorization: Basic NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj" \
    "https://onesignal.com/api/v1/notifications/THE_NOTIFICATION_ID?app_id=YOUR_APP_ID&outcome_names=os__click.count&outcome_platforms=0"
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://onesignal.com/api/v1/notifications/{notification_id}?app_id={appId}&outcome_names=os__click.count&outcome_platforms=0');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');


$headers = array();
$headers[] = 'Authorization: Basic NGEwMGZmMjItY2NkNy0xMWUzLTk5ZDUtMDAwYzI5NDBlNjJj';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

Returned Fields

  • remaining - Number of notifications that have not been sent out yet. This can mean either our system is still processing the notification or you have delayed options set.
  • successful - Number of notifications delivered to the Google/Apple/Windows servers.
  • failed - Number of notifications that could not be delivered due to those devices being unsubscribed.
  • errored - Number of notifications that could not be delivered due to an error. You can find more information by viewing the notification in the dashboard.
  • converted - Number of devices that have clicked/tapped the notification.
  • queued_at - Unix timestamp indicating when the notification was created
  • send_after - Unix timestamp indicating when notification delivery should begin.
  • completed_at - Unix timestamp indicating when notification delivery completed. The delivery duration from start to finish can be calculated with completed_at - send_after.
  • platform_delivery_stats - Hash of delivery statistics broken out by target device platform. See the section below for additional detail.
  • received - Number of devices that confirmed receiving the notification aka Confirmed Deliveries.
  • throttle_rate_per_minute - number of push notifications sent per minute. Paid Feature Only. If throttling is not enabled for the app or the notification, and for free accounts, null is returned. Refer to Throttling for more details.

Outcomes Data response field details

  • id - name of the outcome
  • value - returned value of the aggregation type
  • aggregation - aggregation type (sum or count) requested for the outcome

platform_delivery_stats response field details

Keys present in this hash correspond to the platforms targeted by the notification. For instance, if the push was sent to iOS and Android devices, the hash will have keys ios and android. The full mapping is enumerated below.

  • iOS - ios
  • Android - android
  • Amazon Fire - amazon_fire
  • Windows Phone 8.0 - windows_phone_legacy
  • Chrome Browser Extensions - chrome_extension
  • Chrome Web Push - chrome_web_push
  • Windows Desktop and Phone - windows
  • Safari Browser Push - safari_web_push
  • Firefox Web Push - firefox_web_push
  • macOS Desktop Push - mac_os
  • Alexa Messages - amazon_alexa
  • Email - email
  • SMS - sms. SMS platform delivery stats will feature a delivery report from OneSignal and also from the SMS provider (for example, Twilio).
  • MS Edge Web Push - edge_web_push

Each value in this object is a per-platform object containing:

  1. success: the number of notifications successfully handed off to the upstream provider
  2. failed: the number of notifications rejected by the upstream provider for reasons such as being unsubscribed
  3. errored: the number of messages rejected by the upstream provider for things like configuration errors, server errors, and etc.
  4. converted: the number of messages that have been clicked on, to form a conversion.
  5. received: the number of messages received by the users device.

The following example is for a notification sent to both iOS and Android, and the platform_delivery_stats object contains objects ios and android.

The data in this field can be considered final once delivery is completed -- that is, when the completed_at field has a valid timestamp. During delivery, these values are subject to change.

Result Format - View notification

{
    "adm_big_picture": "",
    "adm_group": "",
    "adm_group_message": {
        "en": ""
    },
    "adm_large_icon": "",
    "adm_small_icon": "",
    "adm_sound": "",
    "spoken_text": {},
    "alexa_ssml": null,
    "alexa_display_title": null,
    "amazon_background_data": false,
    "android_accent_color": "FF9900FF",
    "android_group": "group key",
    "android_group_message": {
        "en": "group message for Android 6.0 and older"
    },
    "android_led_color": null,
    "android_sound": null,
    "android_visibility": 1,
    "app_id": "3beb3078-e0f1-4629-af17-fde833b9f716",
    "big_picture": "https://img.onesignal.com/n/37326fcc-2baa-45da-891c-ca9454a64957.png",
    "buttons": null,
    "canceled": false,
    "chrome_big_picture": "",
    "chrome_icon": "",
    "chrome_web_icon": "https://picture-resource.com/icon-image.png",
    "chrome_web_image": "https://picture-resource.com/image.png",
    "chrome_web_badge": "https://picture-resource.com/badge.png",
    "content_available": false,
    "contents": {
        "en": "English Message"
    },
    "converted": 1,
    "data": {
        "additional": "data",
        "campaign": "25"
    },
    "delayed_option": "immediate",
    "delivery_time_of_day": "2:32PM",
    "errored": 4,
    "excluded_segments": [],
    "failed": 0,
    "firefox_icon": "https://picture-resource.com/firefox_icon.png",
    "global_image": "https://link-to-your-image.com/image-resource-file.png",
    "headings": {
        "en": "English Message Title 😊"
    },
    "id": "fd1723c6-bfaf-4f53-b4f4-0408ff43e18a",
    "include_player_ids": null,
    "include_external_user_ids": null,
    "included_segments": [
        "Subscribed Users"
    ],
    "thread_id": null,
    "ios_badgeCount": 1,
    "ios_badgeType": "Increase",
    "ios_category": "",
    "ios_sound": "explosion.wav",
    "apns_alert": {},
    "isAdm": false,
    "isAndroid": true,
    "isChrome": false,
    "isChromeWeb": true,
    "isAlexa": false,
    "isFirefox": true,
    "isIos": true,
    "isSafari": true,
    "isWP": false,
    "isWP_WNS": false,
    "isEdge": true,
    "large_icon": "https://img.onesignal.com/n/b5cadcf0-1297-4489-b865-545b421d8c5d.png",
    "priority": 5,
    "queued_at": 1580510246,
    "remaining": 0,
    "send_after": 1580510246,
    "completed_at": 1580510247,
    "small_icon": "small_icon",
    "successful": 232,
    "received": 5,
    "tags": null,
    "filters": null,
    "template_id": null,
    "ttl": 777,
    "url": "https://onesignal.com/blog",
    "web_url": null,
    "app_url": null,
    "web_buttons": null,
    "web_push_topic": null,
    "wp_sound": "",
    "wp_wns_sound": "",
    "platform_delivery_stats": {
        "android": {
            "successful": 198,
            "errored": 1,
            "failed": 0,
            "converted": 198,
            "received": 198
        },
        "ios": {
            "successful": 2,
            "errored": 3,
            "failed": 0,
            "converted": 2,
            "received": 2
        }
    },
    "ios_attachments": {
        "id": "https://img.onesignal.com/n/23f60ba6-8f2e-4ce1-bdf5-86e6286c2e39.png"
    },
    "throttle_rate_per_minute": null
}

With Outcomes data

200 OK: (Other keys in the object omitted from this example)

{
 "outcomes": [
   {
     "id": "os__session_duration",
     "value": 300,
     "aggregation": "sum"
   },
   {
     "id": "os__click",
     "value": 2,
     "aggregation": "count"
   },
   {
     "id": "Sales",
     "value": 108,
     "aggregation": "sum"
   }
 ]
}

Applicable Devices for Clicked and Received

Our platform specific clicked and received data is a new feature, as of July 2021. This means we are still working on improving it and gathering feedback. As a result we cannot include all devicess.

Our receieved data will not be shown for:

  • Web Push (Safari)
  • Windows (Phone & Desktop)
  • Apple macOS
  • Chrome Extensions.

Our click tracking doesn't work for:

  • Apple macOS & Windows (Phone & Desktop)

These don't work since we don't have SDKs. Customers could use our public REST API to report them themselves but very unlikely they would.

Language
Authentication
Basic
base64
: