Platform API

The Pushly API is a JSON REST API with base path: https://api.pushly.com.

Authorization

Pushly uses API keys to allow access to the API. The API key is available in the Pushly dashboard to organization Admin users or can be provided by your account manager.

Using the API Key

Example Request

curl 'https://api.p-n.io/domains/1/notifications' -H 'Authorization: Bearer ABCDEFG...'

Once you have generated your key it should be included in an Authorization header with each request to the API:

Authorization: Bearer {key}

Replace {key} with the generated API key.

API Key Expiration

API Keys have a lifetime expiration but can be revoked/regenerated via the platform organization settings page by an organization admin.

Notifications

Retrieve a list of all scheduled & sent notifications

This endpoint returns a list of all notifications that have been scheduled or sent.

Sample Response

{
  "status": "success",
  "data": [
    {
      "source": "MANUAL",
      "id": 360370,
      "domain_id": 1234,
      "is_silent": false,
      "meta": null,
      "created_at": "2019-02-11T19:15:41.779Z",
      "updated_at": "2019-02-11T19:15:41.779Z",
      "template": {
        "channels": {
          "web": {
            "id": 362408,
            "domain_id": 1234,
            "title": "Notification Title",
            "body": "Notification Body",
            "icon_url": "https://example.com/icon-url.jpg",
            "image_url": "https://example.com/image-url.jpg",
            "badge_url": "https://example.com/badge-url.jpg",
            "landing_url": "https://example.com/landing-url.jpg",
            "created_at": "2019-02-11T19:15:41.760Z",
            "updated_at": "2019-02-11T19:15:41.760Z",
            "actions": [
              {
                "id": 86770,
                "type": "OPEN_URL",
                "ordinal": 0,
                "label": "Read More",
                "use_primary_landing_url": true
              }
            ]
          }
        },
        "keywords": [
          "keyword-1",
          "keyword-2"
        ]
      },
      "delivery_spec": {
        "type": "IMMEDIATE",
        "window": "STANDARD",
        "timezone": "America/Chicago",
        "ttl_seconds": 604800,
        "send_date_utc": "2019-02-11T19:15:41.597Z"
      },
      "audience": {
        "segment_ids": [
          4567
        ]
      }
    }
  ],
  "total": 9,
  "count": 9
}

HTTP Request

GET /domains/:domain_id/notifications

URL Parameters

Parameter	Required / Default	Description
domain_id int	Required	The domain for which to retrieve a list of notifications.
limit int	Optional	The number of results to return (ordered by schedule date descending). If not provided, all notifications will be returned.
page int	Optional	If `limit` is provided the page number from which to start. Defaults to 1.
source str	Optional	If provided, filter the creation source to only include specified sources. Valid values are `MANUAL` and `FEED`. If not provided all sources will be returned.

Query Parameters

Parameter	Required / Default	Description
pagination bool	Optional / TRUE	Enable or disable pagination.
page int	Optional / 1	Sets the page for the current request.
limit int	Optional / 15	Sets the max amount of results for the current request. Cannot exceed 250.

Example Request with Query Parameters

GET /domains/:domain_id/notifications?pagination=false

Publish a Notification

This endpoint allows notifications to be scheduled and published.

Sample Request

{
  "audience": {
    "segment_ids": [
      1234,
      5678
    ]
  },
  "template": {
    "channels": {
      "default": {
        "title": "Default Message Title",
        "body": "Default Message Body",
        "landing_url": "https://www.example.com",
        "image_url": "https://www.example.com/image.jpg",
        "icon_url": "https://www.example.com/icon.ico",
        "badge_url": "https://www.example.com/badge.png"
      },
      "web": {
        "title": "Web Override Message Title",
        "body": "Web Override Message Body"
      },
      "native_ios": {
        "landing_url": "myapp://ios/example",
        "subtitle": "iOS Subtitle",
        "sound": "example.wav",
        "interruption_level": "ACTIVE",
        "relevance_score": 0.8
      },
      "native_android": {
        "landing_url": "myapp://android/example"
      }
    },
    "keywords": [
      "keyword 1",
      "keyword-2"
    ]
  },
  "delivery_spec": {
    "type": "SCHEDULED",
    "window": "STANDARD",
    "send_date_utc": "2023-04-13T16:12:00.000Z",
    "ttl_seconds": 259200
  }
}

HTTP Request

POST /domains/:id/notifications

Request Body

Parameter	Required / Default	Description
audience Audience	Required	Defines the subscriber audience that will receive this message.
delivery_spec Delivery Spec	Required	Defines when the notification should be sent.
template Template	Required	Defines the notification details that will be sent.
meta JSON object	Optional	Additional free-form properties for identification and filtering.

Audience

The Audience defines who will receive the notification. Audiences are comprised of 1 to 10 Targeted Segments and optionally up to 10 Excluded Segments.

Parameter	Required / Default	Description
all_subscribers boolean	Optional	Provide `true` to target all subscribers.
segment_ids array<int>	Optional	List of one or more segment IDs.
excluded_segment_ids array<int>	Optional, defaults to no excluded segments	A list of one or more segment IDs to exclude from the targeted audience for this notification.
external_subscriber_ids array<string>	Optional	A list of one or more mapped external subscriber IDs.

Delivery Spec

The Delivery Spec defines when the notification will be delivered.

Parameter	Required / Default	Description
type enum{IMMEDIATE, SCHEDULED}	Required	The following schedule types are supported: `IMMEDIATE`: The notification will be sent immediately. `SCHEDULED`: The notification will be sent at the datetime specified.
window enum{STANDARD,TIMEZONE}	Required	Defines how a notification with `type` of `SCHEDULED` will be delivered: `STANDARD`: The notification will be delivered to all subscribers at the specified datetime. `TIMEZONE`: The notification will be delivered at the specified datetime in the subscriber's time zone.
send_date_utc ISO-8601	Required if type is `SCHEDULED`.	ISO-8601 string representing when the notification should be delivered to the subscriber in UTC.
ttl_seconds int	Optional / 7 days	The number of seconds for which the notification should be attempted to deliver to the subscriber.

Template

The Template defines the visual components of the notification.

Parameter	Required / Default	Description
channels Object	Required	An object containing at least 1 Template Channel
keywords array<string>	Optional	Keywords to attach to the notification.
auto_keyword_discovery bool	Optional	If true, automatically derive keywords for this notification from the primary landing URL. By default this will pull from the meta keywords on the page. Contact your account manager for pulling tags from a custom tag or method.

Template - Channels

A notification can target 1 or more channels. Each channel should be provided as an object keyed by its channel name. Valid channels are:

default: Values provided in the this channel will apply to all other channels unless explicitly provided in another channel.
web: Values for Web Push notifications
native_ios: Values for Native iOS notifications
native_android: Values for Native Android notifications

Default Channel

Parameter	Required / Default	Description
title string	Required	The push notification title to be used unless overridden by a specific channel.
body string	Optional / Empty	The push notification body to be used unless overridden by a specific channel
image_url string	Optional / No Image	URL to a public image to be displayed with the push notification on supported platforms.
icon_url string	Optional / No Image	URL to a public icon to be displayed with the push notification on supported platforms. If not provided, the domain's default icon will be used. To not use the default provide `null`.
badge_url string	Optional / No Image	URL to a public badge to be displayed with the push notification on supported platforms. If not provided, the domain's default badge will be used. To not use the default provide `null`.
landing_url string	Required	The URL that the subscriber will be redirected to after clicking the notification.
actions array<Notification Actions>	Optional	Up to 2 action buttons to include with the notification. If not provided, the domain's default action buttons will be used.
is_silent boolean	Optional, Default `false`	If `true` the notification will not issue sounds or vibrations regardless of the device settings.
require_interaction boolean	Optional, Default `true`	If `false` the notifications on desktop will minimize to the notification center after approximately 8 seconds. Otherwise it requires user interaction to close/minimize.
variations array<Notification Variation>	Optional	Override properties based on profile attributes. See Notification Variations for more information.

Web Channel (web)

{
  "audience": {
    "segment_ids": [
      1234,
      5678
    ]
  },
  "template": {
    "channels": {
      "web": {
        "title": "Default Message Title",
        "body": "Default Message Body",
        "landing_url": "https://www.example.com",
        "image_url": "https://www.example.com/image.jpg",
        "icon_url": "https://www.example.com/icon.ico",
        "badge_url": "https://www.example.com/badge.png"
      }
    },
    "keywords": [
      "keyword 1",
      "keyword-2"
    ]
  },
  "delivery_spec": {
    "type": "SCHEDULED",
    "window": "STANDARD",
    "send_date_utc": "2023-04-13T16:12:00.000Z",
    "ttl_seconds": 259200
  }
}

Parameter	Required / Default	Description
title string	Required	The push notification title.
body string	Optional / Empty	The push notification body
image_url string	Optional / No Image	URL to a public image to be displayed with the push notification on supported platforms.
icon_url string	Optional / No Image	URL to a public icon to be displayed with the push notification on supported platforms. If not provided, the domain's default icon will be used. To not use the default provide `null`.
badge_url string	Optional / No Image	URL to a public badge to be displayed with the push notification on supported platforms. If not provided, the domain's default badge will be used. To not use the default provide `null`.
landing_url string	Required	The URL that the subscriber will be redirected to after clicking the notification.
actions array<Notification Actions>	Optional	Up to 2 action buttons to include with the notification. If not provided, the domain's default action buttons will be used.
is_silent boolean	Optional, Default `false`	If `true` the notification will not issue sounds or vibrations regardless of the device settings.
require_interaction boolean	Optional, Default `true`	If `false` the notifications on desktop will minimize to the notification center after approximately 8 seconds. Otherwise it requires user interaction to close/minimize.
variations array<Notification Variation>	Optional	Override properties based on profile attributes. See Notification Variations for more information.

Native iOS Channel (native_ios)

{
  "audience": {
    "segment_ids": [
      1234,
      5678
    ]
  },
  "template": {
    "channels": {
      "native_ios": {
        "title": "Default Message Title",
        "body": "Default Message Body",
        "subtitle": "iOS Subtitle",
        "landing_url": "myapp://ios/example",
        "image_url": "https://www.example.com/image.jpg",
        "icon_url": "https://www.example.com/icon.ico",
        "badge_url": "https://www.example.com/badge.png",
        "sound": "example.wav",
        "interruption_level": "ACTIVE",
        "relevance_score": 0.8
      }
    },
    "keywords": [
      "keyword 1",
      "keyword-2"
    ]
  },
  "delivery_spec": {
    "type": "SCHEDULED",
    "window": "STANDARD",
    "send_date_utc": "2023-04-13T16:12:00.000Z",
    "ttl_seconds": 259200
  }
}

Parameter	Required / Default	Description
title string	Required	The push notification title to be used.
body string	Optional / Empty	The push notification body to be used.
subtitle string	Optional / Empty	The push notification subtitle to be used..
image_url string	Optional / No Image	URL to a public image to be displayed with the push notification.
icon_url string	Optional / No Image	URL to a public icon to be displayed with the push notification. If not provided, the domain's default icon will be used. To not use the default provide `null`.
landing_url string	Required if not in `default`	The URL that the subscriber will be redirected to after clicking the notification.
category string	Optional	The iOS Category to use.
interruption_level enum {PASSIVE, ACTIVE, TIME_SENSITIVE}	Optional / ACTIVE	The Interruption Level to use for this notification.
relevance_score decimal	Optional / .5	The Relevance Score to use for this notification.
target_content_id string	Optional	The Target Content Identifier to use when the subscriber clicks the notification.
variations array<Notification Variation>	Optional	Override properties based on profile attributes. See Notification Variations for more information.

Native Android Channel (native_android)

{
  "audience": {
    "segment_ids": [
      1234,
      5678
    ]
  },
  "template": {
    "channels": {
      "native_android": {
        "title": "Default Message Title",
        "body": "Default Message Body",
        "landing_url": "myapp://android/example",
        "image_url": "https://www.example.com/image.jpg",
        "icon_url": "https://www.example.com/icon.ico",
        "badge_url": "https://www.example.com/badge.png",
        "channel": "NEWS"
      }
    },
    "keywords": [
      "keyword 1",
      "keyword-2"
    ]
  },
  "delivery_spec": {
    "type": "SCHEDULED",
    "window": "STANDARD",
    "send_date_utc": "2023-04-13T16:12:00.000Z",
    "ttl_seconds": 259200
  }
}

Parameter	Required / Default	Description
title string	Required	The push notification title to be used.
body string	Optional / Empty	The push notification body to be used.
subtitle string	Optional / Empty	The push notification subtitle to be used..
image_url string	Optional / No Image	URL to a public image to be displayed with the push notification.
icon_url string	Optional / No Image	URL to a public icon to be displayed with the push notification. If not provided, the domain's default icon will be used. To not use the default provide `null`.
actions array<Notification Actions>	Optional	Up to 2 action buttons to include with the notification. If not provided, the domain's default action buttons will be used.
landing_url string	Required if not in `default`	The URL that the subscriber will be redirected to after clicking the notification.
channel string	Optional	The Android Notification Channel to use.

Notification Actions

A notification can have up to 2 additional buttons attached that will either take the user to the specified URL or close the notification. If no actions are defined the default actions configured on the domain will be automatically included.

Parameter	Required / Default	Description
ordinal int	Required	The order to show the buttons within the notification. Must be either `0` or `1`.
type enum{OPEN_URL, DISMISS}	Required	The action that will be performed when the button is clicked. The following actions are supported: `OPEN_URL`: The user will be directed to the URL specified in the `landing_url` property. `DISMISS`: The notification will be dismissed on the user's device.
label string	Required	The text that will be shown on the action button.
use_primary_landing_url boolean	Optional	If `type` is `OPEN_URL` and use_primary_landing_url is `true` the primary URL used in the notification will be used for this button. If not provided, will default to `false`.
landing_url string	Optional	Required if `type` is `OPEN_URL` and `use_primary_landing_url` is `false`. The URL that the subscriber will be redirected to after clicking the action button.

Notification Variations

Sample Default Channel with a Mexican Spanish and Canadian French Language Variation

{
  "audience": {
    "all_subscribers": true
  },
  "template": {
    "channels": {
      "default": {
        "title": "Notification Title",
        "body": "Notification Body",
        "landing_url": "https://www.example.com",
        "image_url": "https://www.example.com/image.jpg",
        "variations": [
          {
            "match": {
              "profile.language": "es-mx"
            },
            "values": {
              "title": "Título de la notificación",
              "body": "Descripción de la notificación",
              "image_url": "https://www.example.com/spanish-image.jpg"
            }
          },
          {
            "match": {
              "profile.language": "fr-ca"
            },
            "values": {
              "title": "Titre de la notification",
              "body": "Description de la notification"
            }
          }
        ]
      }
    }
  },
  "delivery_spec": {
    "type": "SCHEDULED",
    "window": "STANDARD",
    "send_date_utc": "2023-04-13T16:12:00.000Z",
    "ttl_seconds": 259200
  }
}

A notification template can include a variations property that will override template properties based on a subscriber's profile attributes.

For example, a variation can be provided that targets subscribers whose device uses a different language than what is provided in the base template. I.e., if the base template provides its title and body in English but you also want to provide a Spanish translation, a separate set of Spanish properties can be provided using a profile.language match statement.

Parameter	Required / Default	Description
match Variation Match>	Required	A JSON object that contains 1 or more Segment Properties as a key value pair.
values Template Channel	Required	Properties of a Template Channel that should be overridden for this variation. If a property is omitted the base template value will be used.

Match any subscriber on desktop device with its language set to Mexican Spanish (es-mx)

{
  "match": {
    "profile.language": "es-mx",
    "profile.placement": "desktop"
  }
}

Edit a Scheduled Notification

This endpoint allows a scheduled notification to be edited or cancelled.

Sample Request

{
  "status": "cancelled"
}

Sample Response

{
  "status": "success",
  "data": {
    "id": 1234,
    "status": "CANCELLED"
  }
}

HTTP Request

PATCH /domains/:id/notifications/:id

Request Body

Parameter	Required / Default	Description
audience Audience	Optional	Defines the subscriber audience that will receive this message.
template Template	Optional	Defines the notification details that will be sent.
delivery_spec Delivery Spec	Optional	Defines when the notification should be sent.
meta JSON object	Optional	Additional free-form properties for identification and filtering.
status enum{CANCELLED}	Optional	Provide `CANCELLED` to cancel the notification. Once a notification has been cancelled it cannot be un-cancelled.

Segments

A segment is a group of subscribers that match specific conditions.

Retrieve a list of all segments

This endpoint returns a list of all segments for a specific domain.

Sample Response

{
  "status": "success",
  "data": [
    {
      "id": 1234,
      "name": "Subscribers 30-90 days old",
      "filters_json": {
        "and": [
          {
            "or": [
              {
                "profile.subscriber_age": {
                  "gt": 30,
                  "meta": {
                    "qualifier": "days"
                  }
                }
              }
            ]
          },
          {
            "or": [
              {
                "profile.subscriber_age": {
                  "lt": 90,
                  "meta": {
                    "qualifier": "days"
                  }
                }
              }
            ]
          }
        ]
      },
      "meta": {
      }
    }
  ]
}

HTTP Request

GET /domains/:domain_id/segments

URL Parameters

Parameter	Required / Default	Description
domain_id int	Required	The domain for which to retrieve a list of segments.

Query Parameters

Parameter	Required / Default	Description
meta.custom_property string \| int	Optional	Custom meta property filters.

Retrieve an individual segment

This endpoint returns information about an existing segment.

Sample Response

{
  "status": "success",
  "data": {
    "id": 1234,
    "domain_id": 5678,
    "name": "Subscribers 30-90 days old",
    "icon_url": "https://www.example.com/icon.jpg",
    "source": "standard",
    "estimated_reach": 1000,
    "is_default": false,
    "filters_json": {
      "and": [
        {
          "or": [
            {
              "profile.subscriber_age": {
                "gt": 30,
                "meta": {
                  "qualifier": "days"
                }
              }
            }
          ]
        },
        {
          "or": [
            {
              "profile.subscriber_age": {
                "lt": 90,
                "meta": {
                  "qualifier": "days"
                }
              }
            }
          ]
        }
      ]
    },
    "meta": {
    }
  }
}

HTTP Request

GET /domains/:domain_id/segments/:segment_id

URL Parameters

Parameter	Required / Default	Description
domain_id int	Required	The domain of the segment to retrieve.
segment_id	Required	The Segment ID of the segment to retrieve.

Create a new Segment

This endpoint creates a new segment based on filters against a subscriber's profile.

Example Request

{
  "name": "Canada & US Desktop Subscribers",
  "filters_json": {
    "and": [
      {
        "or": [
          {
            "profile.country": {
              "eq": "Canada"
            }
          },
          {
            "profile.continent": {
              "eq": "United States"
            }
          }
        ]
      },
      {
        "or": [
          {
            "profile.placement": {
              "eq": "DESKTOP"
            }
          }
        ]
      }
    ]
  },
  "meta": {
  }
}

Example Response

{
  "status": "success",
  "data": {
    "id": 4367,
    "domain_id": 8374,
    "name": "Canada & US Desktop Subscribers",
    "source": "standard",
    "icon_url": null,
    "estimated_reach": 1000,
    "is_default": false,
    "filters_json": {
      "and": [
        {
          "or": [
            {
              "profile.country": {
                "eq": "Canada"
              }
            },
            {
              "profile.continent": {
                "eq": "United States"
              }
            }
          ]
        },
        {
          "or": [
            {
              "profile.placement": {
                "eq": "MOBILE"
              }
            },
            {
              "profile.subscribed_date": {
                "date_in": "last_7_days",
                "meta": {
                  "range": "relative"
                }
              }
            }
          ]
        }
      ]
    },
    "meta": {
    }
  }
}

HTTP Request

POST /domains/:domain_id/segments

Request Body

Parameter	Required / Default	Description
domain_id int	Required	The domain id in which the segment will be created.
name string	Required	A unique name for this segment.
filters_json JSON	Required	A query fragment that will return a list of subscribers. A fragment always contains at least one `"and": [...]` block with `"or": [..]` blocks within. See the Segment Properties section of the documentation.
meta JSON object	Optional	Additional free-form properties for identification and filtering.

Segment Properties

Property	Description	Values	Comparators
profile.allow_url	The URL the subscriber was visiting on subscribed.	A complete URL, URL fragment, or string that the URL contains.	`eq`, `neq`, `contains`, `not_contains`
profile.continent_code	The last continent the user was in when using the subscribed device.	A valid 2-letter continent code. Case insensitive.	`eq`, `neq`
profile.country_code	The last country the user was in when using the subscribed device.	A valid ISO 3166-1 alpha-2 country code.	`eq`, `neq`
profile.province	The last state / province the user was in when using the subscribed device.	A valid state or province name. Case insensitive.	`eq`, `neq`
profile.city	The last continent the user was in when using the subscribed device.	A valid continent name. Case insensitive.	`eq`, `neq`, `contains`, `not_contains`
profile.postal_code	The last zip or postal code the user was in when using the subscribed device.	A valid zip or postal code.	`eq`, `neq`
profile.placement	The device type on which the user subscribed.	`DESKTOP`, `MOBILE`, `TABLET`	`eq`, `neq`
profile.navigator	The last user agent the the subscriber was using when using the subscribed device.	String to match against the user agent.	`eq`, `neq`, `contains`, `not_contains`
profile.device_os	The last operating system the subscriber was using when using the subscribed device.	String to match against operating system name.	`contains`, `not_contains`
profile.tag	Will match all subscribers who have clicked a notification with the specified keyword.	A previously used keyword in notification creation.	`eq`, `neq`, `contains`, `not_contains`
profile.last_seen	The number of days since we last saw the subscriber using the subscribed device.	A valid ISO-8601 date string.	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`
profile.language	The number of days since we last saw the subscriber using the subscribed device.	An IETF language tag or ISO 639-1 language code.	`eq`, `neq`
profile.subscriber_age	The number of days since the subscriber first opted-in to notifications.	Integer number of days.	`eq`, `neq`, `gt`, `gte`, `lt`, `lte`
profile.subscribed_date	The date the subscriber opted-in to notifications.	A valid ISO-8601 date string.	See Date Properties
Custom Field	A custom field provided via the SDK. All custom fields be automatically prefixed with `profile.`	Supports string comparison only.	`eq`, `neq`, `contains`, `not_contains`

Segment Comparators

Comparator	Description
eq	Equals
neq	Not equals
gt	Greater than
gte	Greater than or equal to
lt	Less than
lte	Less than or equal to
contains	String contains provided value
not_contains	String does not contain provided value

Segment Date Properties

Meta	Required	Description
meta.range string	Required	`relative`: A sliding window based on the value provided for `date_in` will be used. `exact`: The exact date provided will always be used.
date_in enum{today, yesterday, last_7_days, last_14_days, last_30_days, last_90_days, this_week, last_week, this_month, last_month}	Required when `meta.range` is `relative`.	A relative date string that specifies an inclusive rolling range of dates to include.
eq ISO-8601	Required when `meta.range` is `exact`	The date to exact match against.

Update an existing Segment

This endpoint updates an existing segment based on filters against a subscriber's profile.

Example Request

{
  "name": "Canada & Mexico Subscribers",
  "filters_json": {
    "and": [
      {
        "or": [
          {
            "profile.country": {
              "eq": "Canada"
            }
          },
          {
            "profile.continent": {
              "eq": "Mexico"
            }
          }
        ]
      }
    ]
  },
  "meta": {
  }
}

HTTP Request

PUT /domains/:domain_id/segments/:segment_id

Request Body

Parameter	Required / Default	Description
domain_id int	Required	The domain of the segment to be updated.
segment_id int	Required	The segment ID to update.
name string	Required	A unique name for this segment.
filters_json JSON	Required	A query fragment that will return a list of subscribers. A fragment always contains at least one `"and": [...]` block with `"or": [..]` blocks within. See the Segment Properties table for valid filters.
meta JSON	Additional properties for identification and filtering.

Delete a Segment

HTTP Request

DELETE /domains/:domain_id/segments/:segment_id

Request Body

Parameter	Required / Default	Description
domain_id int	Required	The domain of the segment to be deleted.
segment_id int	Required	The segment ID to delete.

Reporting

The Insights API provides an interface to fetch aggregated metrics for notifications.

Example Notification Request

{
  "entity": "notifications",
  "breakdowns": [
    "notification"
  ],
  "date_range": {
    "since": "1955-11-05",
    "through": "1955-11-12"
  },
  "fields": [
    "notification_id",
    "notification_title",
    "notification_body",
    "notification_scheduled_time",
    "notification_audiences",
    "notification_icon_url",
    "notification_badge_url",
    "notification_image_url",
    "notification_keywords",
    "notification_landing_url",
    "notification_lifespan",
    "notification_created_by",
    "impressions",
    "clicks",
    "ctr_decimal",
    "purchases",
    "purchase_amount"
  ]
}

Example Response URL

{
  "report_url": "https://pushly-sw-prod-filestack.s3.amazonaws.com/reports/xyz"
}

Example Notification Response JSON

{
  "data": [
    {
      "send_date": "1955-11-05",
      "impressions": 438398,
      "clicks": 31995,
      "ctr_decimal": 0.073,
      "purchases": 4,
      "purchase_amount": 3021.00,
      "notification": {
        "id": 891011213,
        "title": "Roads?",
        "body": "Where we're going, we don't need roads.",
        "scheduled_time": "2020-04-11 08:19:11",
        "icon_url": "https://upload.wikimedia.org/wikipedia/commons/1/1b/Back_to_the_Future_film_series_logo.png",
        "badge_url": "https://cdn3.iconfinder.com/data/icons/back-to-the-future/512/delorean-04-128.png",
        "image_url": "https://upload.wikimedia.org/wikipedia/en/d/d2/Back_to_the_Future.jpg",
        "keywords": [
          "grey's sports almanac",
          "delorean"
        ],
        "landing_url": "https://en.wikipedia.org/wiki/Back_to_the_Future",
        "lifespan": "1 Day",
        "created_by": "Emmett Brown",
        "audiences": {
          "excluded": [],
          "targeted": [
            {
              "type": "segment",
              "label": "Hill Valley Subscribers",
              "value": 123
            }
          ]
        }
      }
    }
  ]
}

Example Prompt Request

{
  "entity": "prompts",
  "breakdowns": [
    "domain"
  ],
  "date_range": {
    "since": "1955-11-05",
    "through": "1955-11-12"
  },
  "fields": [
    "permissions_shown",
    "permissions_dismissed",
    "permissions_denied",
    "subscriptions",
    "subscription_rate_decimal"
  ]
}

Example Prompt Response JSON

{
  "data": [
    {
      "event_date": "1955-11-05",
      "permissions_shown": 1461826,
      "subscriptions": 134111,
      "subscription_rate_decimal": 0.0917,
      "domain": {
        "id": 8849
      }
    },
    {
      "event_date": "1955-11-12",
      "permissions_shown": 1485053,
      "subscriptions": 137320,
      "subscription_rate_decimal": 0.0925,
      "domain": {
        "id": 8849
      }
    }
  ]
}

HTTP Request

POST /domains/:domain_id/insights

Due to a current limitation the Insights API will always return a link to a S3 URL. The contents of this URL should be downloaded to receive the payload for the requested report. Alternatively, you can add forceJson=1 to the URL to receive the results directly, but if the result set is too large you may receive an error. For example: /domains/:domain_id/insights?forceJson=1

Request Body

Parameter	Required / Default	Description
entity enum{notifications,prompts}	Required	The type of report to pull. `notifications` will provide delivery stats, `prompts` provide acquisition stat.
breakdowns array<Notification Breakdown, Prompt Breakdown>	Required	One or more of the specified entity's dimensions that the data should be grouped by.
date_range {since: YYYY-MM-DD, through: YYYY-MM-DD}	Required	The exact date range for which to constrain the data.
fields array<Notification Field, Prompt Field>	Required, at least 1 field related to the specified entity	One or more fields to return.

Notification Breakdowns

Property	Description
domain	Group results at the Domain level
notification	Group results at the Notification level
browser	Group results by the subscriber's browser
placement	Group results by the subscriber's placement / device type (mobile, desktop, tablet)

Notification Fields

Property	Description
notification_id	Notification ID
notification_title	Notification Title
notification_body	Notification Body
notification_scheduled_time	Text representation of the datetime the notification was scheduled in the domain's time zone. This field can also be a text string for notifications that are created as part of a campaign.
notification_audiences	Object containing a `targeted` and `excluded` list property. Each object within the list contains a `type`, `label`, and `value` (segment ID) property.
notification_icon_url	URL of the icon used in the notification
notification_badge_url	URL of the badge used in the notification
notification_image_url	URL of the image used in the notification
notification_keywords	Keywords attached to the notification
notification_landing_url	The primary landing URL used in the notification
notification_lifespan	Text representation of the time period the notification was attempted to be delivered
notification_created_by	The name or email address of the user who created the notification
campaign_id	Campaign ID to which this notification is attached
campaign_name	Campaign Name to which this notification is attached
step_id	Campaign Step ID to which this notification is attached
impressions	The number of subscribers who saw the notification
clicks	The number of subscribers who clicked on the notification
ctr_decimal	The click-through rate for the notification in decimal format
purchases	The number of purchases attributed to the notification within the configured attribution window
purchase_amount	The total purchase amount attributed to the notification within the configured attribution window

Prompt Breakdowns

Property	Description
domain	Group results at the Domain level
browser	Group results by the subscriber's browser
placement	Group results by the subscriber's placement / device type (mobile, desktop, tablet)

Prompt Fields

Property	Description
permissions_shown	The number of times a permission dialog was displayed
permissions_dismissed	The number of times a permission dialog was dismissed
permissions_denied	The number of times a permission dialog was denied
subscriptions	The number of visitors that allowed notification permissions
subscription_rate_decimal	The rate at which visitors allowed notification permissions
prompts_shown	The number of times a soft prompt was displayed
prompts_dismissed	The number of times a soft prompt was dismissed
prompts_shown_non_unique	The number of times a soft prompt was shown (includes multiple shows to a visitor)
prompts_dismissed_non_unique	The number of times a soft prompt was dismissed (includes multiple dismisses for a visitor)
prompts_accepted	The number of times a soft prompt was allowed
prompt_accept_rate_decimal	The The rate at which visitors allowed the soft prompt

Live Activities

Implement one of our Apple SDKs to add Live Activities to your native application. Then use the following methods to send updates to your Live Activity subscribers.

Update a Live Activity

This endpoint sends updated content to a Live Activity's subscribers.

Example Request

{
  "name": "Activity Name",
  "event": "update",
  "relevance_score": 100,
  "priority": 10,
  "content_state": {
    "team_1_score": 14,
    "team_2_score": 7,
    "clock_time": "8:31"
  },
  "notification": {
    "title": "Score updated!",
    "body": "The score of the game you're tracking has changed.",
    "sound": "score.aiff"
  }
}

Example Response

{
  "status": "success",
  "data": {
    "id": "c72b3104-4e05-4af3-919c-6C3a794ef24c"
  }
}

HTTP Request

POST /domains/:domain_id/live-activities/:activity_id

Request Body

Parameter	Required / Default	Description
name string	Required	A name for this Live Activity; This value will be used for reporting purposes.
event enum{UPDATE,END}	Required	Whether the activity should be updated or ended.
relevance_score integer	Optional / 100	Determines the order in which your Live Activities appear when you start several Live Activities for your app. Use a higher value for an important Live Activity content update — for example, a score of 100 — and use lower values for less important Live Activity content updates — for example, 50.
priority integer	Optional / 10	See Apple Documentaton
stale_date ISO-8601 string or Unix timestamp	Optional	When time reaches the configured stale date, the system considers the Live Activity out of date.
dismissal_date ISO-8601 string or Unix timestamp	Optional	When the Live Activity should be removed from the lock screen. If not provided it will remain for up to 4 hours after it was ended.
content_state JSON object	Optional	A JSON object that matches the content state definition for your Live Activity. Provide the data that should be dynamically updated on each subscribers' device.
notification Live Activity Notification	Optional	On Apple Watch, the system uses the title and body attributes for the alert. On iPhone and iPad, the system doesn’t show a regular alert but instead shows the expanded Live Activity in the Dynamic Island or the Lock Screen presentation as a banner on devices without the Dynamic Island.

Live Activity Notification

Parameter	Required / Default	Description
title string	Required	A short title that describes the purpose of the Live Activity update on Apple Watch.
body string	Optional	The main text that appears on the alert for a Live Activity update on Apple Watch.
sound string	Optional	The filename of the sound the system plays when the Live Activity alert appears on a device.

Errors

The Pushly API returns the following HTTP responses:

Error Code	Meaning
200	OK -- The request was successful.
400	Bad Request -- The request is invalid.
403	Unauthorized -- The API key is invalid or expired.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- The method provided is not available for this resource.
500	Internal Server Error -- An unknown issue occurred with the request. Try again or contact support.
503	Service Unavailable -- Pushly is temporarily offline for maintenance. Please try again later.

User Deletion API

A user deletion request can be sent via an API POST call to the following endpoint which returns an empty body and a 204 response code:

https://k.p-n.io/event-stream

The user deletion request will be received by our team and processed within 30 days. Your account manager will inform you when the request has been completed.

Sample Request

{
  "action": "udr",
  "domain_id": 1234,
  "external_id": "abcd1234"
}

Request Body

The POST body should be a JSON object with the following properties:

Parameter	Description
action string	A string with static value `udr`
domain_id int	The Pushly domain ID from where this request was initiated
external_id string	The mapped external subscriber ID of the actor requesting user deletion