Query Parameters

user_id
string
(uuid)

Only display tokens associated with the User ID.

show_invalid
boolean

Determines whether to include invalidated tokens

page_size
integer
(int32)

Sets the number of items to return in paginated endpoints

page
integer
(int32)

Sets the page number for paginated endpoints

Response

200 Device Tokens
data
object[]

Resource Data

app_id
string

App ID the Token belongs to

created
string
(date-time)

When the Token was created

id
string

Token ID. A MD5 hash of the device token

invalidated
string
(date-time)

When the Token was last invalidated

token
string

Device Token

type
string

Platform of the Token

valid
boolean

Validity of the Token

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Saves a device token that was previously generated by a device platform.

Request Body

schema application/json
token
string

Device Token

user_id
string
(uuid)

User ID. Associate the token with the User.

Response

201 Created Token
data
object

Resource Data

app_id
string

App ID the Token belongs to

created
string
(date-time)

When the Token was created

id
string

Token ID. A MD5 hash of the device token

invalidated
string
(date-time)

When the Token was last invalidated

token
string

Device Token

type
string

Platform of the Token

valid
boolean

Validity of the Token

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Get information about a specific Token. Remember to use an MD5 hash of the token string you are trying to retrieve for the Token ID.

Path Parameters

token_id
string

Token ID (MD5 Hash of the token)

Response

200 Device Token
data
object

Resource Data

app_id
string

App ID the Token belongs to

created
string
(date-time)

When the Token was created

id
string

Token ID. A MD5 hash of the device token

invalidated
string
(date-time)

When the Token was last invalidated

token
string

Device Token

type
string

Platform of the Token

valid
boolean

Validity of the Token

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Path Parameters

token_id
string

Token ID (MD5 Hash of the token)

Request Body

schema application/json
valid
boolean

Determines whether the device token is valid

Response

200 Updated Device Token
data
object

Resource Data

app_id
string

App ID the Token belongs to

created
string
(date-time)

When the Token was created

id
string

Token ID. A MD5 hash of the device token

invalidated
string
(date-time)

When the Token was last invalidated

token
string

Device Token

type
string

Platform of the Token

valid
boolean

Validity of the Token

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Path Parameters

token_id
string

Token ID (MD5 Hash of the token)

Response

204 No Content

Path Parameters

token_id
string

Token ID (MD5 Hash of the token)

Query Parameters

page_size
integer
(int32)

Sets the number of items to return in paginated endpoints

page
integer
(int32)

Sets the page number for paginated endpoints

Path Parameters

user_id
string
(uuid)

User ID

token_id
string

Token ID (MD5 Hash of the token)

Response

204 No Content

Path Parameters

user_id
string
(uuid)

User ID

token_id
string

Token ID (MD5 Hash of the token)

Response

204 No Content

Get Message details. Use this endpoint to check the current status of a message or to lookup the error code for failures.

Path Parameters

message_id
string

Message ID

Response

200 Push Notification Message
data
object

Resource Data

created
string
(date-time)

When the Message was created

error
string

Messaged failed due to this error

Possible Values

INVALID

Severe error. Please check our status page or open an issue.

UNKNOWN

GCM or APNS may be experiencing trouble.

UNABLE_TO_AUTH

TODO: is this even possible?

NO_CREDENTIAL

Security Profile not found or does not have the appropriate credentials. You will need GCM credentials for Android and APNS credentials for iOS.

INVALID_MESSAGE_FORMAT

Your notification had an invalid payload.

ILLEGAL_CREDENTIAL_FORMAT

The credentials on your Security Profile are invalid. You may need to regenerate and re-upload.

INVALID_CREDENTIAL_PASSWORD

The password on your credential’s certificate was incorrect. You can verify the password by using OpenSSL (openssl pkcs12 -in Certificates.p12).

NO_VALID_TOKENS

Your request didn’t target any valid tokens. If you’re sending via user IDs, ensure those users have device tokens.

INVALID_TOKEN

The device token has been marked invalid. Re-register the device.

APNS_BAD_TOPIC

Invalid APNS topic (bundle ID) or the bundle ID in your certificate does not match your app.

APNS_TOPIC_DISALLOWED

Sending pushes to the APNS topic was not allowed. Are Apple Push Notifications enabled for your app? Is the bundle ID of your certificate correct?

APNS_BAD_DEVICE_TOKEN

Verify that you specified a valid token and that your Security Profile’s type (development/production) matches your push certificate’s type.

APNS_DEVICE_TOKEN_NOT_FOR_TOPIC

The device token does not match the specified topic. You may be using a device token from a different app.

APNS_UNREGISTERED

The device token is no longer active for your app.

APNS_BAD_CERTIFICATE_ENVIRONMENT

Your certificate was used in the wrong environment (production vs development). Make sure your Security Profile’s type (development/production) matches your push certificate’s type.

APNS_BAD_CERTIFICATE

For some reason, your certificate was bad. APNS does not tell us more. Try regenerating the certificate for your app.

GCM_INVALID_AUTH

You could have an incorrect GCM project number or API key, or have the service disabled. Also make sure you have not set up an IP whitelist.

GCM_ERROR

Something has gone wrong in GCM.

GCM_INVALID_REGISTRATION

Your request contained an incorrect device token (registration_id). Check that you’re entering the token in correctly.

GCM_INVALID_PACKAGE

Invalid package name. Make sure the message was addressed to a registration token whose package name matches the value passed in the request.

GCM_MISMATCH_SENDER

When a client app registers for GCM, it must specify which senders are allowed to send messages. If you switch to a different sender, the existing registration tokens won’t work.

GCM_TOO_BIG

The total size of the payload data included in a message must not exceed 4096 bytes.

GCM_INVALID_KEY

The payload data must not contain keys such as from, gcm, or any value prefixed by google.

GCM_INVALID_TTL

The value used in time_to_live is an integer between 0 and 2,419,200 (seconds).

GCM_UNKNOWN

Something went wrong on while communicating with GCM. Please check our status page or open an issue.

notification_id
string
(uuid)

Parent Notification ID

status
string

Current status

token
object

Message was sent to this token

app_id
string

App ID the Token belongs to

created
string
(date-time)

When the Token was created

id
string

Token ID. A MD5 hash of the device token

invalidated
string
(date-time)

When the Token was last invalidated

token
string

Device Token

type
string

Platform of the Token

valid
boolean

Validity of the Token

user_id
string
(uuid)

Message was tied to this User ID

uuid
string
(uuid)

Message ID

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Path Parameters

message_id
string

Message ID

Response

204 No Content

Paginated listing of Push Notifications for an App

Query Parameters

page_size
integer
(int32)

Sets the number of items to return in paginated endpoints

page
integer
(int32)

Sets the page number for paginated endpoints

fields
string[]

Additional Fields to return

Additional Fields

message_total
string

Total number of messages tied to the notification

overview
string

Get an overview of messages delivered and failed for a given notification

Response

200 Push Notifications
data
object[]

Resource Data

app_id
string

App ID the Notification belongs to.

config
object

Notification Config

android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

created
string
(date-time)

Time of Notification creation

overview
object

Notification Overview Schema

errors
object

Notification Overview Error Schema

count
integer
(int32)

The number of times this error code was seen

reason
string

The error code seen within this notification

invalid
integer
(int32)

The number of invalid tokens for this notification

sent
integer
(int32)

The number of messages accepted by FCM/APNS

state
string

Current state of the Notication in regards to our processing pipeline. The final state is enqueued. This means the notification has been processed and is now in the process of generating Message objects.

Possible Values

pending

Notification has not begun processing

scheduled

Notification is waiting for the scheduled time to begin processing.

failed

Notification encountered an error on our end and will not attempt to resend. This does not indicate an error with the format of your notification.

enqueued

Notification successfully processed. Messages should now be generated.

status
string

Determines whether or not the Notification can be modified

Possible Values

open

Modifications are still allowed.

locked

No modifications can be made as the Notification has already generated messages.

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Create a Push Notification

In the following examples, fill in the following:

DEVICE_TOKEN The device token you registered and saved
PROFILE_TAG The Security Profile tag found in Settings › Certificates in the Dashboard

You can send a push notification directly to a device token like so:

{
    "tokens": ["DEVICE_TOKEN"],
    "profile": "PROFILE_TAG",
    "notification": {
        "message": "Hello World!"
    }
}

Targeting Options

You can send to more than just device tokens, however. Depending on which authentication providers you have enabled, you can use the following targeting fields:

Field Provider  
tokens   Device Tokens
user_ids Email/Password User UUIDs
emails Email/Password User email addresses
external_ids Custom User IDs on your server
facebook_ids Facebook Facebook IDs
google_ids Google Google IDs
twitter_ids Twitter Twitter IDs (not handles)
linkedin_ids LinkedIn LinkedIn IDs
github_ids Github Github IDs
send_to_all   Ignore targeting and send to all devices

Platform Overrides

You can override notification fields per platform.

{
    "tokens": ["DEVICE_TOKEN"],
    "profile": "PROFILE_TAG",
    "notification": {
        "message": "Hello World!",
        "ios": {
            "message": "Hello iOS!"
        },
        "android": {
            "message": "Hello Android"
        }
    }
}

Request Body

schema application/json
emails
string[]

Targets User email address for delivery

external_ids
string[]

Targets Custom Authentication User IDs for delivery

facebook_ids
string[]

Targets Facebook User IDs for delivery

github_ids
string[]

Targets Github User IDs for delivery

google_ids
string[]

Targets Google+ User IDs for delivery

instagram_ids
string[]

Targets Instagram User IDs for delivery

linkedin_ids
string[]

Targets LinkedIn User IDs for delivery

notification
object

Notification Config

android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

profile
string

Security Profile Tag to use when sending Messages

scheduled
string

Time to start delivery of the notification

send_to_all
boolean

Targets all valid Device Tokens for delivery, ignores other delivery options

tokens
string[]

Targets Device Tokens for delivery

twitter_ids
string[]

Targets Twitter User IDs for delivery

user_ids
string[]

Targets User IDs for delivery

Response

200 Notification
data
object

Resource Data

app_id
string

App ID the Notification belongs to.

config
object

Notification Config

android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

created
string
(date-time)

Time of Notification creation

overview
object

Notification Overview Schema

errors
object

Notification Overview Error Schema

count
integer
(int32)

The number of times this error code was seen

reason
string

The error code seen within this notification

invalid
integer
(int32)

The number of invalid tokens for this notification

sent
integer
(int32)

The number of messages accepted by FCM/APNS

state
string

Current state of the Notication in regards to our processing pipeline. The final state is enqueued. This means the notification has been processed and is now in the process of generating Message objects.

Possible Values

pending

Notification has not begun processing

scheduled

Notification is waiting for the scheduled time to begin processing.

failed

Notification encountered an error on our end and will not attempt to resend. This does not indicate an error with the format of your notification.

enqueued

Notification successfully processed. Messages should now be generated.

status
string

Determines whether or not the Notification can be modified

Possible Values

open

Modifications are still allowed.

locked

No modifications can be made as the Notification has already generated messages.

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Path Parameters

notification_id
string
(uuid)

Notification ID

Query Parameters

fields
string[]

Additional Fields to return

Additional Fields

overview
string

Get an overview of messages delivered and failed for a given notification

Response

200
data
object

Resource Data

app_id
string

App ID the Notification belongs to.

config
object

Notification Config

android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

created
string
(date-time)

Time of Notification creation

state
string

Current state of the Notication in regards to our processing pipeline. The final state is enqueued. This means the notification has been processed and is now in the process of generating Message objects.

Possible Values

pending

Notification has not begun processing

scheduled

Notification is waiting for the scheduled time to begin processing.

failed

Notification encountered an error on our end and will not attempt to resend. This does not indicate an error with the format of your notification.

enqueued

Notification successfully processed. Messages should now be generated.

status
string

Determines whether or not the Notification can be modified

Possible Values

open

Modifications are still allowed.

locked

No modifications can be made as the Notification has already generated messages.

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Path Parameters

notification_id
string
(uuid)

Notification ID

Request Body

schema application/json
emails
string[]

Targets User email address for delivery

external_ids
string[]

Targets Custom Authentication User IDs for delivery

facebook_ids
string[]

Targets Facebook User IDs for delivery

github_ids
string[]

Targets Github User IDs for delivery

google_ids
string[]

Targets Google+ User IDs for delivery

instagram_ids
string[]

Targets Instagram User IDs for delivery

linkedin_ids
string[]

Targets LinkedIn User IDs for delivery

notification
object

Notification Config

android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

profile
string

Security Profile Tag to use when sending Messages

scheduled
string

Time to start delivery of the notification

send_to_all
boolean

Targets all valid Device Tokens for delivery, ignores other delivery options

tokens
string[]

Targets Device Tokens for delivery

twitter_ids
string[]

Targets Twitter User IDs for delivery

user_ids
string[]

Targets User IDs for delivery

Response

200 Notification
data
object

Resource Data

app_id
string

App ID the Notification belongs to.

config
object

Notification Config

android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

created
string
(date-time)

Time of Notification creation

overview
object

Notification Overview Schema

errors
object

Notification Overview Error Schema

count
integer
(int32)

The number of times this error code was seen

reason
string

The error code seen within this notification

invalid
integer
(int32)

The number of invalid tokens for this notification

sent
integer
(int32)

The number of messages accepted by FCM/APNS

state
string

Current state of the Notication in regards to our processing pipeline. The final state is enqueued. This means the notification has been processed and is now in the process of generating Message objects.

Possible Values

pending

Notification has not begun processing

scheduled

Notification is waiting for the scheduled time to begin processing.

failed

Notification encountered an error on our end and will not attempt to resend. This does not indicate an error with the format of your notification.

enqueued

Notification successfully processed. Messages should now be generated.

status
string

Determines whether or not the Notification can be modified

Possible Values

open

Modifications are still allowed.

locked

No modifications can be made as the Notification has already generated messages.

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Path Parameters

notification_id
string
(uuid)

Notification ID

Response

204 No Content

Path Parameters

notification_id
string
(uuid)

Notification ID

Query Parameters

page_size
integer
(int32)

Sets the number of items to return in paginated endpoints

page
integer
(int32)

Sets the page number for paginated endpoints

Response

200 Notification's Messages
data
object[]

Resource Data

created
string
(date-time)

When the Message was created

error
string

Messaged failed due to this error

Possible Values

INVALID

Severe error. Please check our status page or open an issue.

UNKNOWN

GCM or APNS may be experiencing trouble.

UNABLE_TO_AUTH

TODO: is this even possible?

NO_CREDENTIAL

Security Profile not found or does not have the appropriate credentials. You will need GCM credentials for Android and APNS credentials for iOS.

INVALID_MESSAGE_FORMAT

Your notification had an invalid payload.

ILLEGAL_CREDENTIAL_FORMAT

The credentials on your Security Profile are invalid. You may need to regenerate and re-upload.

INVALID_CREDENTIAL_PASSWORD

The password on your credential’s certificate was incorrect. You can verify the password by using OpenSSL (openssl pkcs12 -in Certificates.p12).

NO_VALID_TOKENS

Your request didn’t target any valid tokens. If you’re sending via user IDs, ensure those users have device tokens.

INVALID_TOKEN

The device token has been marked invalid. Re-register the device.

APNS_BAD_TOPIC

Invalid APNS topic (bundle ID) or the bundle ID in your certificate does not match your app.

APNS_TOPIC_DISALLOWED

Sending pushes to the APNS topic was not allowed. Are Apple Push Notifications enabled for your app? Is the bundle ID of your certificate correct?

APNS_BAD_DEVICE_TOKEN

Verify that you specified a valid token and that your Security Profile’s type (development/production) matches your push certificate’s type.

APNS_DEVICE_TOKEN_NOT_FOR_TOPIC

The device token does not match the specified topic. You may be using a device token from a different app.

APNS_UNREGISTERED

The device token is no longer active for your app.

APNS_BAD_CERTIFICATE_ENVIRONMENT

Your certificate was used in the wrong environment (production vs development). Make sure your Security Profile’s type (development/production) matches your push certificate’s type.

APNS_BAD_CERTIFICATE

For some reason, your certificate was bad. APNS does not tell us more. Try regenerating the certificate for your app.

GCM_INVALID_AUTH

You could have an incorrect GCM project number or API key, or have the service disabled. Also make sure you have not set up an IP whitelist.

GCM_ERROR

Something has gone wrong in GCM.

GCM_INVALID_REGISTRATION

Your request contained an incorrect device token (registration_id). Check that you’re entering the token in correctly.

GCM_INVALID_PACKAGE

Invalid package name. Make sure the message was addressed to a registration token whose package name matches the value passed in the request.

GCM_MISMATCH_SENDER

When a client app registers for GCM, it must specify which senders are allowed to send messages. If you switch to a different sender, the existing registration tokens won’t work.

GCM_TOO_BIG

The total size of the payload data included in a message must not exceed 4096 bytes.

GCM_INVALID_KEY

The payload data must not contain keys such as from, gcm, or any value prefixed by google.

GCM_INVALID_TTL

The value used in time_to_live is an integer between 0 and 2,419,200 (seconds).

GCM_UNKNOWN

Something went wrong on while communicating with GCM. Please check our status page or open an issue.

notification_id
string
(uuid)

Parent Notification ID

status
string

Current status

token
object

Message was sent to this token

app_id
string

App ID the Token belongs to

created
string
(date-time)

When the Token was created

id
string

Token ID. A MD5 hash of the device token

invalidated
string
(date-time)

When the Token was last invalidated

token
string

Device Token

type
string

Platform of the Token

valid
boolean

Validity of the Token

user_id
string
(uuid)

Message was tied to this User ID

uuid
string
(uuid)

Message ID

meta
object

Response Metadata

request_id
string
(uuid)

Request Reference ID

status
integer
(int32)

HTTP Response Code

version
string
(semver)

API Version

Models

The following is a collection of model references

AndroidNotificationConfig

schema application/json
collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

Notification

schema application/json
app_id
string

App ID the Notification belongs to.

config
object

Notification Config

android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

created
string
(date-time)

Time of Notification creation

overview
object

Notification Overview Schema

errors
object

Notification Overview Error Schema

count
integer
(int32)

The number of times this error code was seen

reason
string

The error code seen within this notification

invalid
integer
(int32)

The number of invalid tokens for this notification

sent
integer
(int32)

The number of messages accepted by FCM/APNS

state
string

Current state of the Notication in regards to our processing pipeline. The final state is enqueued. This means the notification has been processed and is now in the process of generating Message objects.

Possible Values

pending

Notification has not begun processing

scheduled

Notification is waiting for the scheduled time to begin processing.

failed

Notification encountered an error on our end and will not attempt to resend. This does not indicate an error with the format of your notification.

enqueued

Notification successfully processed. Messages should now be generated.

status
string

Determines whether or not the Notification can be modified

Possible Values

open

Modifications are still allowed.

locked

No modifications can be made as the Notification has already generated messages.

NotificationOverviewError

schema application/json
count
integer
(int32)

The number of times this error code was seen

reason
string

The error code seen within this notification

NotificationConfig

schema application/json
android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

IOSNotificationConfig

schema application/json
badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

Token

schema application/json
app_id
string

App ID the Token belongs to

created
string
(date-time)

When the Token was created

id
string

Token ID. A MD5 hash of the device token

invalidated
string
(date-time)

When the Token was last invalidated

token
string

Device Token

type
string

Platform of the Token

valid
boolean

Validity of the Token

NotificationInput

schema application/json
emails
string[]

Targets User email address for delivery

external_ids
string[]

Targets Custom Authentication User IDs for delivery

facebook_ids
string[]

Targets Facebook User IDs for delivery

github_ids
string[]

Targets Github User IDs for delivery

google_ids
string[]

Targets Google+ User IDs for delivery

instagram_ids
string[]

Targets Instagram User IDs for delivery

linkedin_ids
string[]

Targets LinkedIn User IDs for delivery

notification
object

Notification Config

android
object

Android Notification Options

collapse_key
string

Identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to GCM

delay_while_idle
boolean

When this parameter is set to true, it indicates that the message should not be sent until the device becomes active.

icon
string

Filename of the Icon to display with the notification

image
string

Filename or URI of an image file to display with the notification

message
string

Message Text

payload
object

Custom data

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default Android device notification sound

tag
string

Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

time_to_live
integer
(int32)

This parameter specifies how long (in seconds) the message should be kept in GCM storage if the device is offline

title
string

Notification Title

ios
object

iOS Notification Options

badge
integer
(int32)

The number to display as the badge of the app icon

content_available
integer
(int32)

Determines if the message should be delivered as a silent notification. A value of 1 will cause the message to be delivered as a background notification, which will not display a notification to the user, but the application can still process the notification.

data
object

Raw data sent to APNS

expire
string

Time at which APNS will stop trying to deliver the notification

message
string

Notification Text

payload
object

Custom data

priority
integer
(int32)

Message Priority. A value of 10 will cause APNS to attempt immediate delivery. A value of 5 will attempt a delivery which is convenient for battery life.

sound
string

Filename of audio file to play when a notification is received. Setting this to default will use the default iOS device notification sound

template_defaults
object

Default values to for template variables when a corresponding user does not have a value

title
string

Alert Title, only applicable for iWatch devices

message
string

Notification text

payload
object

Payload data

title
string

Notification title to show on devices as applicable

profile
string

Security Profile Tag to use when sending Messages

scheduled
string

Time to start delivery of the notification

send_to_all
boolean

Targets all valid Device Tokens for delivery, ignores other delivery options

tokens
string[]

Targets Device Tokens for delivery

twitter_ids
string[]

Targets Twitter User IDs for delivery

user_ids
string[]

Targets User IDs for delivery

AutomatedNotification

schema application/json
activated
string

When the automated notification was activated

app_id
string

App ID

is_active
boolean

Notifications will only be triggered if this is true

name
string

Reference Name

uuid
string

Automated Notification ID

Message

schema application/json
created
string
(date-time)

When the Message was created

error
string

Messaged failed due to this error

Possible Values

INVALID

Severe error. Please check our status page or open an issue.

UNKNOWN

GCM or APNS may be experiencing trouble.

UNABLE_TO_AUTH

TODO: is this even possible?

NO_CREDENTIAL

Security Profile not found or does not have the appropriate credentials. You will need GCM credentials for Android and APNS credentials for iOS.

INVALID_MESSAGE_FORMAT

Your notification had an invalid payload.

ILLEGAL_CREDENTIAL_FORMAT

The credentials on your Security Profile are invalid. You may need to regenerate and re-upload.

INVALID_CREDENTIAL_PASSWORD

The password on your credential’s certificate was incorrect. You can verify the password by using OpenSSL (openssl pkcs12 -in Certificates.p12).

NO_VALID_TOKENS

Your request didn’t target any valid tokens. If you’re sending via user IDs, ensure those users have device tokens.

INVALID_TOKEN

The device token has been marked invalid. Re-register the device.

APNS_BAD_TOPIC

Invalid APNS topic (bundle ID) or the bundle ID in your certificate does not match your app.

APNS_TOPIC_DISALLOWED

Sending pushes to the APNS topic was not allowed. Are Apple Push Notifications enabled for your app? Is the bundle ID of your certificate correct?

APNS_BAD_DEVICE_TOKEN

Verify that you specified a valid token and that your Security Profile’s type (development/production) matches your push certificate’s type.

APNS_DEVICE_TOKEN_NOT_FOR_TOPIC

The device token does not match the specified topic. You may be using a device token from a different app.

APNS_UNREGISTERED

The device token is no longer active for your app.

APNS_BAD_CERTIFICATE_ENVIRONMENT

Your certificate was used in the wrong environment (production vs development). Make sure your Security Profile’s type (development/production) matches your push certificate’s type.

APNS_BAD_CERTIFICATE

For some reason, your certificate was bad. APNS does not tell us more. Try regenerating the certificate for your app.

GCM_INVALID_AUTH

You could have an incorrect GCM project number or API key, or have the service disabled. Also make sure you have not set up an IP whitelist.

GCM_ERROR

Something has gone wrong in GCM.

GCM_INVALID_REGISTRATION

Your request contained an incorrect device token (registration_id). Check that you’re entering the token in correctly.

GCM_INVALID_PACKAGE

Invalid package name. Make sure the message was addressed to a registration token whose package name matches the value passed in the request.

GCM_MISMATCH_SENDER

When a client app registers for GCM, it must specify which senders are allowed to send messages. If you switch to a different sender, the existing registration tokens won’t work.

GCM_TOO_BIG

The total size of the payload data included in a message must not exceed 4096 bytes.

GCM_INVALID_KEY

The payload data must not contain keys such as from, gcm, or any value prefixed by google.

GCM_INVALID_TTL

The value used in time_to_live is an integer between 0 and 2,419,200 (seconds).

GCM_UNKNOWN

Something went wrong on while communicating with GCM. Please check our status page or open an issue.

notification_id
string
(uuid)

Parent Notification ID

status
string

Current status

token
object

Message was sent to this token

app_id
string

App ID the Token belongs to

created
string
(date-time)

When the Token was created

id
string

Token ID. A MD5 hash of the device token

invalidated
string
(date-time)

When the Token was last invalidated

token
string

Device Token

type
string

Platform of the Token

valid
boolean

Validity of the Token

user_id
string
(uuid)

Message was tied to this User ID

uuid
string
(uuid)

Message ID

NotificationOverview

schema application/json
errors
object

Notification Overview Error Schema

count
integer
(int32)

The number of times this error code was seen

reason
string

The error code seen within this notification

invalid
integer
(int32)

The number of invalid tokens for this notification

sent
integer
(int32)

The number of messages accepted by FCM/APNS

Services

    API

      General