NAV Navbar
  • API
  • API

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

    Authorization

    Pushly uses API keys to allow access to the API. Your account manager can provide you the necessary credentials to use when generating an API key.

    Generating an API Key

    This endpoint generates an API key from an email address and password.

    Sample Request

    {
      "email": "api-user@example.com",
      "password": "p4ss0wrd"
    }
    

    Samples Response

    {
      "status": "success",
      "token": "ABCDEFG..."
    }
    

    HTTP Request

    POST /auth/login

    Request Body

    Parameter Required / Default Description
    email
    string
    Required The email address for your API user.
    password
    string
    Required The set password for your API user.

    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}

    API Key Expiration

    Although a generated API key has a lifetime expiration, there are other scenarios which may cause the key to expire or become invalid. You must validate the response status of API calls to ensure the key has not expired. A 403 response indicates that the key has expired and needs to be re-generated before the API will accept subsequent requests.

    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
            ]
          },
          "meta": {
            ...
          }
        },
        ...
      ],
      "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": {
          "web": {
            "title": "Message Title",
            "body": "Message Body",
            "landing_url": "http://www.example.com",
            "image_url": "http://www.example.com/image.jpg",
            "icon_url": "http://www.example.com/icon.ico",
            "badge_url": "http://www.example.com/badge.png",
          }
        },
        "keywords": ["keyword 1", "keyword-2"],
        "auto_keyword_discovery": false
      },
      "delivery_spec": {
        "type": "SCHEDULED",
        "window": "STANDARD",
        "send_date_utc": "2018-08-04T16:12:00.000Z",
        "ttl_seconds": 259200
      },
      "meta": {
        ...
      }
    }
    

    Samples Response

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

    HTTP Request

    POST /domains/:id/notifications

    Request Body

    Parameter Required / Default Description
    audience
    Audience
    Required Defines the subscriber audience that will receive this message.
    template
    Template
    Required Defines the notification details that will be sent.
    delivery_spec
    Delivery Spec
    Required Defines when the notification should 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.
    Template

    The Template defines the visual components of the notification.

    Parameter Required / Default Description
    channels.web.title
    string
    Required The web push notification title.
    channels.web.body
    string
    Optional / Empty The web push notification body.
    channels.web.image_url
    string
    Optional / No Image URL to a public image to be displayed with the push notification on supported platforms.
    channels.web.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.
    channels.web.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.
    channels.web.landing_url
    string
    Required The URL that the user will be redirected to after clicking the notification.
    channels.web.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.
    channels.web.is_silent
    boolean
    Optional, Default false If true the notification will not issue sounds or vibrations regardless of the device settings.
    channels.web.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.
    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.
    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
    YYYY-MM-DDThh:mmTZD
    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.
    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 user will be redirected to after clicking the action button.

    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.is_desktop": {
                  "eq": true
                }
              }
            ]
          }
        ]
      },
      "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.is_desktop": {
                    "eq": true
                  }
                },
                {
                  "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 The last continent the user was in when visiting the domain. A valid continent name. Case insensitive. eq, neq
    profile.country The last country the user was in when visiting the domain. A valid country name. Case insensitive. eq, neq
    profile.province The last state / province the user was in when visiting the domain. A valid state or province name. Case insensitive. eq, neq
    profile.city The last continent the user was in when visiting the domain. 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 visiting the domain. A valid zip or postal code. eq, neq
    profile.is_desktop The user subscribed via a Desktop device / browser. true or false eq, neq
    profile.is_mobile The user subscribed via a mobile device / browser. true or false eq, neq
    profile.navigator The last user agent the the subscriber was using when visiting the domain. String to match against the user agent. eq, neq, contains, not_contains
    profile.device_os The last operating system the subscriber was using when visiting the domain. 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 visiting the domain. A valid ISO-8601 date string. eq, neq, gt, gte, lt, lte
    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 Javascript SDK. All custom fields sent via the SDK will 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_count"
      ]
    }
    

    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
          }
        }
      ]
    }
    

    Example Pub Network Request

    {
      "entity": "pub_network",
      "breakdowns": [
        "domain"
      ],
      "date_range": {
        "since": "1955-11-05",
        "through": "1955-11-12"
      },
      "fields": [
        "impressions",
        "paid_clicks",
        "paid_ctr_decimal",
        "revenue",
      ]
    }
    

    Example Pub Network Response JSON

    {
      "data": [
        {
          "report_date": "1955-11-05",
          "impressions": 3797652,
          "paid_clicks": 16028,
          "paid_ctr_decimal": 0.0042,
          "revenue": 636.37
        },
        {
          "report_date": "1955-11-12",
          "impressions": 3800077,
          "paid_clicks": 17146,
          "paid_ctr_decimal": 0.0045,
          "revenue": 655.9
        }
      ]
    }
    

    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.

    Request Body

    Parameter Required / Default Description
    entity
    enum{notifications,prompts,pub_network}
    Required The type of report to pull. notifications will provide delivery stats, prompts provide acquisition stats and, if you have access, pub_network will provide ad stats.
    breakdowns
    array<Notification Breakdown, Prompt Breakdown, Pub Network 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, Pub Network Fields >
    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
    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

    Pub Network Breakdowns

    Property Description
    domain Group results at the Domain level

    Pub Network Fields

    Property Description
    impressions The number of notification impressions
    paid_clicks The number of paid clicks
    paid_ctr_decimal The paid clicks click-through rate in decimal format
    revenue The amount of revenue generated from paid clicks

    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.