API Reference

Making Requests

The ZeroPush HTTP API is designed to be simple and predictable using standard HTTP conventions. Building a client should be straight-forward and well supported in a wide variety of languages and environments. Each HTTP endpoint in the reference handles requests and responses with a common parameter and authentication scheme.

All HTTP requests are served from the host https://api.zeropush.com

Parameters

Parameters passed to the API can be either application/x-www-form-urlencoded or application/json encoded. Requests should pass a Content-Type header based on the encoding. If no Content-Type header is used, the API will default to form-encoded parameters.

Examples

All of the examples below will illustrate making requests using cURL due to it's ubiquity and wide support. The examples are made from a Bash-like command line so certain cURL parameters are quoted using single quotes and multiple lines are broken apart using a backslash.

An example of a cURL request using form-encoded parameters (default content-type):

curl https://api.zeropush.com/broadcast \
  -d auth_token=Za1u98vb \
  -d alert=foobar
An example of a cURL request using JSON parameters:
curl https://api.zeropush.com/broadcast \
  -H 'Content-Type: application/json' \
  -d '{"auth_token":"Za1u98vb", "alert":"foobar"}'


Authentication

Authenticating with ZeroPush is simple using HTTP Headers, query parameters or form-encoded parameters by providing an auth_token.

There are two types of auth tokens:

  • server_token - Use this for making requests from your web app. Look for the icon next to the endpoint.
  • app_token - Use this token in your mobile app. Look for the icon next to the endpoint.

The app_token is distributed with your mobile app and it has less privileges than the server_token.
The server_token is the only one that can send Push Notifications via /notify and /broadcast

Note Make sure you keep your server_token secret!


Examples

In the examples below, wherever auth_token is referenced, substitute it with your server_token or app_token depending on context.

  1. Query Parameter:
    curl https://api.zeropush.com/verify_credentials?auth_token=auth_token
  2. Form-encoded POST Parameter:
    curl https://api.zeropush.com/register \
      -d auth_token=auth_token
  3. HTTP Header:
    curl https://api.zeropush.com/verify_credentials \
      -H 'Authorization: Token token="auth_token"'
    

Responses

All responses will return data in JSON. Successful responses will have a status code in the 2xx range.

Errors

Response status codes that are in the 4xx range indicate an error from the provided information (e.g. missing authentication, missing or invalid require parameters, etc.)
Status codes in the 5xx range indicate a problem with ZeroPush's servers.

Errors are returned in JSON and have the following attributes:

  • error - short description of the type of error
  • message - an explanation of the error
  • reference_url - URL that can provide more information about solving the error

Examples

Examples of common error responses with headers:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Status: 401 Unauthorized
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

{
  "error":"authorization error",
  "message":"Please provide a valid authentication token parameter or HTTP Authorization header.",
  "reference_url":"https://zeropush.com/documentation/api_reference#authorization"
}
HTTP/1.1 403 Forbidden
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Status: 403 Forbidden
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

{
  "error":"quota error",
  "message":"Current usage: 1001 notifications, exceeds your plan's quota of 1000 notifications.",
  "reference_url":"https://zeropush.com/documentation/api_reference"
}
HTTP/1.1 412 Precondition Failed
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Status: 412 Precondition Failed
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

{
  "error":"configuration error",
  "message":"The requested application has not been configured.",
  "reference_url":"https://zeropush.com/documentation/api_reference"
}


API Endpoints

GET /verify_credentials accepted token

Verifies whether credentials have been configured properly

Required Parameters
auth_token String

A token to authenticate use of the API. Can be either server_token or app_token.


Examples

Request
curl https://api.zeropush.com/verify_credentials?auth_token=auth_token
Response

If a valid auth_token was supplied, a Success response will be returned along with the auth_token type that was used to make the request.

{"message":"authenticated", "auth_token_type":"server_token"}

If an invalid token was used to make the request, an Unauthorized response will be returned.

{"error":"unauthorized"}
POST /notify accepted token

Sends a notification to a list of device tokens.

Required Parameters
device_tokens Array

An array of device tokens to notify


Optional Parameters
alert String/JSON

The text of the notification to be displayed. If you want to customize the notification, you may pass extended arguments as Alert JSON

badge Integer/String

The number to display on the app's icon badge. badge can also auto-increment or auto-decrement by passing "+1" or "-1" respectively.

sound String

A sound to play along with the notification

info String

A JSON dictionary of extra data to send with the notification

expiry Integer

A UNIX epoch date expressed in seconds (UTC) that identifies when the notification is no longer valid and can be discarded.

content_available Boolean

The presence of this parameter will cause the notification to include the content_available key in it's aps payload. The only valid truthy value is 'true'. This is used to implement background fetch.

category String

A string matching the identifier of a registered interactive notification type.


Customizing Alert JSON
body String

The text of the alert message.

action-loc-key String

If a string is specified, the system displays an alert that includes the Close and View buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of "View". See “Localized Formatted Strings” for more information.

loc-key String

A key to an alert-message string in a Localizable.strings file for the current localization (which is set by the user’s language preference). The key string can be formatted with %@ and % n $@ specifiers to take the variables specified in loc-args. See “Localized Formatted Strings” for more information.

loc-args Array

Variable string values to appear in place of the format specifiers in loc-key. See “Localized Formatted Strings” for more information.

launch-image String

The filename of an image file in the application bundle; it may include the extension or omit it. The image is used as the launch image when users tap the action button or move the action slider. If this property is not specified, the system either uses the previous snapshot,uses the image identified by the UILaunchImageFile key in the application's Info.plist file, or falls back to Default.png.


Examples

Request
curl https://api.zeropush.com/notify \
  -d 'auth_token=auth_token' \
  -d 'device_tokens[]=device_token' \
  -d 'alert=Hello from curl' \
  -d 'info={"user_id":1234}' \
  -d 'badge=1'
Response

successful response

{
  "sent_count":1,
  "inactive_tokens":[],
  "unregistered_tokens":[]
}
Required Parameters
device_tokens Array

An array of device tokens to notify

title String

The text of the notification to be displayed.

body String

The body of the notification.


Optional Parameters
url_args Array

Array of values to substitute placeholders of urlFormatString defined in website.json.

label String

The label of the action button, if the user sets the notifications to appear as alerts. This label should be succinct, such as “Details” or “Read more”. If omitted, the default value is “Show”.

expiry Integer

A UNIX epoch date expressed in seconds (UTC) that identifies when the notification is no longer valid and can be discarded.


Examples

Request
curl https://api.zeropush.com/notify \
     -d auth_token=auth_token \
     -d device_tokens[]=device_token \
     -d "title=Now Boarding" \
     -d "body=Boarding Flight A998." \
     -d "label=View"
Response

successful response

{
  "sent_count":1,
  "inactive_tokens":[],
  "unregistered_tokens":[]
}
Required Parameters
device_tokens Array

An array of device tokens to notify

data JSON/Hash

The payload delivered to the app.


Optional Parameters
collapse_key String

This parameter specifies an arbitrary string (such as "Updates Available") that is used to collapse a group of like messages when the device is offline, so that only the last message gets sent to the client. This is intended to avoid sending too many messages to the phone when it comes back online. Note that since there is no guarantee of the order in which messages get sent, the "last" message may not actually be the last message sent by the application server. Messages with collapse keys are also called send-to-sync messages.

Note: GCM allows a maximum of 4 different collapse keys to be used by the GCM server at any given time. In other words, the GCM server can simultaneously store 4 different send-to-sync messages per device, each with a different collapse key. If you exceed this number GCM will only keep 4 collapse keys, with no guarantees about which ones they will be.

delay_while_idle Boolean

This parameter indicates that the message should not be sent immediately if the device is idle. The server will wait for the device to become active, and then only the last message for each collapse_key value will be sent. The default value is false.

time_to_live Integer

This parameter specifies how long (in seconds) the message should be kept on GCM storage if the device is offline. Optional (default time-to-live is 4 weeks, and must be set as a JSON number).


Examples

Request
curl https://api.zeropush.com/notify \
     -d 'auth_token=auth_token' \
     -d 'device_tokens[]=device_token' \
     -d 'data[alert]=Now Boarding' \
     -d 'data[username]=fred.droid'
Successful Response
{
  "sent_count":1,
  "inactive_tokens":[],
  "unregistered_tokens":[]
}

Headers

Notification requests include the following HTTP response headers regarding your account's quota usage.

  • X-Push-Quota - your plan's monthly quota of push notifications.
  • X-Push-Quota-Remaining - the remaining push notifications within your plan.
  • X-Push-Quota-Overage - any amount of overage you have accrued.
  • X-Push-Quota-Reset - the number of seconds until the monthly quota is reset.

Plans that have an Infinite quota limit will have Infinite as values of the headers.

POST /broadcast/{channel} accepted token

Sends a notification to all registered and active devices.
See /register for more information.

If the channel parameter is specified, only devices subscribed to that channel will receive notifications.
See /subscribe for more information.

Optional Parameters
alert String/JSON

The text of the notification to be displayed. If you want to customize the notification, you may pass extended arguments as Alert JSON

badge Integer/String

The number to display on the app's icon badge. badge can also auto-increment or auto-decrement by passing "+1" or "-1" respectively.

sound String

A sound to play along with the notification

info String

A JSON dictionary of extra data to send with the notification

expiry Integer

A UNIX epoch date expressed in seconds (UTC) that identifies when the notification is no longer valid and can be discarded.

content_available Boolean

The presence of this parameter will cause the notification to include the content_available key in it's aps payload. The only valid truthy value is 'true'. This is used to implement background fetch.

channel String

The name of the broadcast channel to notify.

category String

A string matching the identifier of a registered interactive notification type.


Customizing Alert JSON
body String

The text of the alert message.

action-loc-key String

If a string is specified, the system displays an alert that includes the Close and View buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of "View". See “Localized Formatted Strings” for more information.

loc-key String

A key to an alert-message string in a Localizable.strings file for the current localization (which is set by the user’s language preference). The key string can be formatted with %@ and % n $@ specifiers to take the variables specified in loc-args. See “Localized Formatted Strings” for more information.

loc-args Array

Variable string values to appear in place of the format specifiers in loc-key. See “Localized Formatted Strings” for more information.

launch-image String

The filename of an image file in the application bundle; it may include the extension or omit it. The image is used as the launch image when users tap the action button or move the action slider. If this property is not specified, the system either uses the previous snapshot,uses the image identified by the UILaunchImageFile key in the application's Info.plist file, or falls back to Default.png.


Examples

Request
curl https://api.zeropush.com/broadcast  \
     -d auth_token=auth_token        \
     -d alert="Hello from curl"          \
     -d badge=1                          \
Response

successful response

{
  "sent_count":100
}
Required Parameters
title String

The text of the notification to be displayed.

body String

The body of the notification.


Optional Parameters
url_args Array

Array of values to substitute placeholders of urlFormatString defined in website.json.

label String

The label of the action button, if the user sets the notifications to appear as alerts. This label should be succinct, such as “Details” or “Read more”. If omitted, the default value is “Show”.

expiry Integer

A UNIX epoch date expressed in seconds (UTC) that identifies when the notification is no longer valid and can be discarded.

channel String

The name of the broadcast channel to notify.


Examples

Request
curl https://api.zeropush.com/broadcast \
     -d auth_token=auth_token \
     -d title="Hello from curl" \
Response

successful response

{
  "sent_count":100
}
Required Parameters
data JSON/Hash

The payload delivered to the app.


Optional Parameters
channel String

The name of the broadcast channel to notify.

collapse_key String

This parameter specifies an arbitrary string (such as "Updates Available") that is used to collapse a group of like messages when the device is offline, so that only the last message gets sent to the client. This is intended to avoid sending too many messages to the phone when it comes back online. Note that since there is no guarantee of the order in which messages get sent, the "last" message may not actually be the last message sent by the application server. Messages with collapse keys are also called send-to-sync messages.

Note: GCM allows a maximum of 4 different collapse keys to be used by the GCM server at any given time. In other words, the GCM server can simultaneously store 4 different send-to-sync messages per device, each with a different collapse key. If you exceed this number GCM will only keep 4 collapse keys, with no guarantees about which ones they will be.

delay_while_idle Boolean

This parameter indicates that the message should not be sent immediately if the device is idle. The server will wait for the device to become active, and then only the last message for each collapse_key value will be sent. The default value is false.

time_to_live Integer

This parameter specifies how long (in seconds) the message should be kept on GCM storage if the device is offline. Optional (default time-to-live is 4 weeks, and must be set as a JSON number).


Examples

Request
curl https://api.zeropush.com/broadcast \
     -d 'auth_token=auth_token' \
     -d 'data[alert]=Now Boarding' \
     -d 'data[username]=fred.droid'
Successful Response
{
  "sent_count":1,
  "inactive_tokens":[],
  "unregistered_tokens":[]
}

Headers

Notification requests include the following HTTP response headers regarding your account's quota usage.

  • X-Push-Quota - your plan's monthly quota of push notifications.
  • X-Push-Quota-Remaining - the remaining push notifications within your plan.
  • X-Push-Quota-Overage - any amount of overage you have accrued.
  • X-Push-Quota-Reset - the number of seconds until the monthly quota is reset.

Plans that have an Infinite quota limit will have Infinite as values of the headers.

POST /register accepted token

Registers a device and/or updates the devices active status

Required Parameters
device_token String

The device token to register


Optional Parameters
channel String

Optional channel to which the device should be subscribed


Examples

Request
curl https://api.zeropush.com/register \
     -d auth_token=auth_token \
     -d device_token=device_token \
Response
{"message": "ok"}

Headers

Registration requests include the following HTTP response headers regarding your account's quota usage.

  • X-Device-Quota - your plan's quota of devices.
  • X-Device-Quota-Remaining - the remaining device registrations within your plan.
  • X-Device-Quota-Overage - the number of devices beyond your plan's quota.

Plans that have an Infinite quota limit will have Infinite as values of the headers.

DELETE /unregister accepted token

Unregisters a previously registered device token

Required Parameters
device_token String

The device token to unregister


Examples

Request
curl -X DELETE https://api.zeropush.com/unregister?auth_token=auth_token&device_token=device_token
Response
{"message": "ok"}

Headers

Registration requests include the following HTTP response headers regarding your account's quota usage.

  • X-Device-Quota - your plan's quota of devices.
  • X-Device-Quota-Remaining - the remaining device registrations within your plan.
  • X-Device-Quota-Overage - the number of devices beyond your plan's quota.

Plans that have an Infinite quota limit will have Infinite as values of the headers.

POST /subscribe/{channel} accepted token

Subscribes a device to a particular notification channel

Required Parameters
device_token String

The token of the device to subscribe

channel String

The channel to which the device should be subscribed


Examples

Request
curl https://api.zeropush.com/subscribe/foo  \
     -d auth_token=auth_token  \
     -d device_token=device_token
Response
{
  "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf",
  "channels":["foo"]
}
DELETE /subscribe/{channel} accepted token

Unsubscribes a device from a particular notification channel

Required Parameters
device_token String

The token of the device to unsubscribe

channel String

The channel from which to unsubscribe


Examples

Request
curl -X DELETE https://api.zeropush.com/subscribe/foo?auth_token=auth_token&device_token=device_token
Response
{
  "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf",
  "channels":[]
}
GET /inactive_tokens accepted token

Returns an array of device tokens along with the time each token was marked inactive

Optional Parameters
since Integer

Unix timestamp. Returns all of the devices that have been marked inactive since this time.

Examples

Request
  curl https://api.zeropush.com/inactive_tokens?auth_token=auth_token&since=1363033513
Response
[
  {
    "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf",
    "marked_inactive_at": "2013-03-11T16:25:14-04:00",
    "marked_inactive": 1363033514
  },
  {
    "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf",
    "marked_inactive_at": "2013-03-11T16:25:14-04:00",
    "marked_inactive": 1363033514
  }
]
POST /set_badge accepted token

Sets a device's badge number to a given value

Required Parameters
device_token String

The token of the device to set the badge on

badge Integer

The badge number to set


Examples

Request
curl https://api.zeropush.com/set_badge \
     -d auth_token=auth_token \
     -d device_token=device_token \
     -d badge=5
Response
{"message": "ok"}
GET /devices accepted token

Get a paginated result set of all devices registered to the app.

Optional Parameters
page Integer

The page indicates where to begin in the collection of devices.

per_page Integer

The number of devices per page. Maximum of 100 and defaults to 25.


Examples

Request
curl https://api.zeropush.com/devices?auth_token=auth_token
Response
[
  {"token":"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf","active":true,"marked_inactive_at":null,"badge":1},
  {"token":"234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf0","active":true,"marked_inactive_at":null,"badge":2}
]

Headers

The JSON response contains a paginated result set. To navigate the pages, please refer to the Total and Link headers.

  • Link - The Link header contains 4 URLs with different rel values for navigating: next, last, first, prev
    Link: <https://api.zeropush.com/devices?page=10&per_page=25>; rel="last",
    <https://api.zeropush.com/devices?page=2&per_page=25>; rel="next"
  • Total - Returns the total number of devices for a given app.
GET /devices/{device_token} accepted token

Get details about a particular device.

Required Parameters
device_token String

The token of the device


Examples

Request
curl https://api.zeropush.com/devices/device_token?auth_token=auth_token
Response
{"token":"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf","active":true,"marked_inactive_at":null,"badge":1,"channels":["testflight", "user@example.com"]}
PUT /devices/{device_token} accepted token

Replace the channel subscriptions with a new set of channels. This will remove all previous subscriptions of the device. If you want to append a list of channels, use PATCH.

Required Parameters
device_token String

The token of the device

channel_list String

Comma separated list of channels.


Examples

Request
curl -X PUT https://api.zeropush.com/devices/device_token \
  -d auth_token=auth_token \
  -d channel_list=player-1,game-256
Response
{"token":"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf","active":true,"marked_inactive_at":null,"badge":1,"channels":["player-1", "game-256"]}
PATCH /devices/{device_token} accepted token

Append the channel subscriptions with a set of new channels. If you want to replace the list of channels, use PUT.

Required Parameters
device_token String

The token of the device

channel_list String

Comma separated list of channels.


Examples

Request
curl -X PATCH https://api.zeropush.com/devices/device_token \
  -d auth_token=auth_token \
  -d channel_list=player-1,game-256
Response
{"token":"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf","active":true,"marked_inactive_at":null,"badge":1,"channels":["player-1", "game-256", "testflight", "user@example.com"]}
GET /channels accepted token

Get a paginated list of all channels that have been created for this app and have at least 1 device subscribed to it.

Optional Parameters
page Integer

The page indicates where to begin in the collection of channel.

per_page Integer

The number of channels per page. Maximum of 100 and defaults to 25.


Examples

Request
curl https://api.zeropush.com/channels?auth_token=auth_token
Response
["player-1","player-2","player-9","game-256","admins","lobby"]
GET /channels/{channel_name} accepted token

Get details about this channel.

Required Parameters
channel_name String

The name of channel to query


Examples

Request
curl https://api.zeropush.com/channels/player-1?auth_token=auth_token
Response
{"channel":"player-1","device_tokens":["1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf"]}
DELETE /channels/{channel_name} accepted token

Unsubscribe all devices and delete this channel.

Required Parameters
channel_name String

The name of channel to delete


Examples

Request
curl -X DELETE https://api.zeropush.com/channels/player-1?auth_token=auth_token
Response
{"channel":"player-1","device_tokens":["1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcedf"]}
Response returns the channel that was deleted and all of the devices that have been unsubscribed. No device token will be deleted.
updated on Sat Feb 7 16:45:50 2015