Was this helpful?

This topic provides information on setting up and sending push notifications with the Apigee API backend as a service (BaaS). For high-level information, prerequisites, and tutorials, see Push notifications overview.

Although not shown in many of the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.
For an overview of how to set up push notifications, including troubleshooting tips, see Adding push notifications support.

Creating notifications

When you create a notification, it is scheduled to be delivered to all applicable devices immediately unless the deliver property has been set. A notification may contain multiple messages (payloads), and each payload must be associated with a notifier in order to deliver that message to the associated app. This allows a single notification to be delivered to multiple apps across various services, and is useful if you want to send messages to multiple notifiers, such as development and production versions of both Apple and Google simultaneously.

Notification can be created via POST request to the BaaS API, or in the admin portal:

Targeting a single device

This request will target a specific device entity.

Request Syntax

curl -X POST https://api.usergrid.com/<org>/<app>/devices/<device_ID>/notifications -d '{"payloads":{<notifier>:<message>}}'

Targeting all devices

This request will target all device entities.

Request Syntax

curl -X POST https://api.usergrid.com/<org>/<app>/devices/*/notifications -d '{"payloads":{<notifier>:<message>}}'

Targeting a single user

This request will target a specific user entity.

Request Syntax

curl -X POST https://api.usergrid.com/<org>/<app>/users/<username>/notifications -d '{"payloads":{<notifier>:<message>}}'

Targeting a group

This request will target all users associated with a specific group entity.

Request Syntax

curl -X POST https://api.usergrid.com/<org>/<app>/groups/<group_path>/notifications -d '{"payloads":{<notifier>:<message>}}'

Targeting users by location

This request will target all device entities that are within a set radius of a latitude/longitude coordinate.

Request Syntax

curl -X POST https://api.usergrid.com/<org>/<app>/devices;ql=location within <radius> of <lat>,<long>/notifications -d '{"payloads":{<notifier>:<message>}}'

Request Parameters

The following parameters can be specified when targeting push notifications.

Base URL

These parameters are used in forming the base URL of the request:

Parameter Description
org Organization UUID or organization name
app Application UUID or application name


These parameters are used when forming the notification portion of the request:

Parameter Description
notifier The notifier entity you wish to associate with the notification (see Creating notifiers for information on creating notifiers)

The push notitfication message that will be delivered to the user

Note: If your message contains double-quotes ("") you must escape them with a backslash


These parameters are used when specifying the notification target in the request.

Parameter Description
device UUID of a device entity.
user UUID or username of a user entity.
phone_type Specified in a appended query string. The type property of a device entity.
group UUID or name of the group entity.
latitude, longitude, radius Specified in a appended query string. The radius in meters of a user device from a latitude/longitude coordinate.

To create the new notification with the admin portal, do the following:

  1. Log in to the admin portal.
  2. In the left nav, click Push > Send Notification.
  3. From the Notifier drop-down, select the appropriate notifier.
  4. Under the notifier name, select one of the following to specify where your notification message should go:
    • All Devices to have the message sent to all devices.
    • Devices to have the message sent to a particular subset of devices. Enter a comma-separated list of device UUIDs in the box provided.
    • Users to have the message sent to a particular subset of users. Enter a comma-separated list of username values in the box provided.
    • Groups to have the message sent to a particular subset of user groups. Enter a comma-separated list of group paths in the box provided.
  5. In the Notifier Message field, enter the message (payload) you want delivered.
    • If double-quotes are included in your message, you must escape them with a backslash.
  6. Under Delivery, select one of the following to specify when the notification should be delivered:
    • Now to have the message delivered immediately.
    • Schedule for later to choose a date and time at which the message should be delivered.
  7. Click Submit.

To create a notification to send multiple messages or target multiple platforms, see the cURL syntax for creating notifications.

To send notifications from iOS app code, you use the ApigeeAPSDestination and ApigeeAPSPayload classes.

With ApigeeAPSDestination, you specify where the notification should go (a particular user or device or user group, for example). With ApigeeAPSPayload, you specify the contents of the message, including any alert text, sound, or badge (items specified by Apple as allowable notification content types). You then use ApigeeDataClient to send the message via Apigee and Apple APNs.

The following code illustrates how to send a notification to a single user. Though this is the device on which the app itself is installed, you can imagine how you might send a notification to another device, such as one belonging to someone "following" this user. For more, see the iOS push sample application included with the Apigee iOS SDK.

- (void)sendMyselfAPushNotification:(NSString *)message
    // send to a single device -- our own device
    NSString *deviceId = [ApigeeDataClient getUniqueDeviceID];
    ApigeeAPSDestination* destination =
        [ApigeeAPSDestination destinationSingleDevice:deviceId];
    // set our APS payload
    ApigeeAPSPayload* apsPayload = [[ApigeeAPSPayload alloc] init];
    apsPayload.sound = kBundledSoundNameWithExt;
    apsPayload.alertText = message;
    // Example of what a custom payload might look like -- remember that
    // APNS payloads are limited to a maximum of 256 bytes (for the entire
    // payload -- including the 'aps' part)
    NSMutableDictionary* customPayload = [[NSMutableDictionary alloc] init];
    [customPayload setValue:@"72" forKey:@"degrees"];
    [customPayload setValue:@"3" forKey:@"newOrders"];
    __weak AppDelegate* weakSelf = self;
    // send the push notification
    [dataClient pushAlert:apsPayload
        completionHandler:^(ApigeeClientResponse *response) {
            if ( ! [response completedSuccessfully]) {
                [weakSelf alert:response.rawResponse
                          title: @"Error"];
            if (completionHandler) {

Scheduling notifications

To schedule a notification for a later time, add the deliver parameter with a UNIX timestamp to the body of your request.

Request body syntax


Targeting multiple notifiers or messages

To send multiple messages or target multiple platforms with a single notification entity, include multiple notifier-message pairs as a comma-separated list in the payloads object of the request body:

Request body syntax

'{"payloads":{<notifier>:<message>, <notifier>:<message>, ...}}'

Setting a notification expiration

If a push service can't deliver a message to a device and needs to resend it (for example, if the device is turned off), you can set a notification to expire after a certain date/time.

To do this, adding the expire parameter with a UNIX timestamp to your request body. This specifies when the service should stop trying to send the notification.

Request body syntax


Getting notifications

The following are endpoints can be used to get notifications. For details on the notification properties you can get, see Notifier, Receipt, and Notification.

Getting one or more notifications:


Getting notifications associated with one or more receipts:


Getting the list of devices associated with one or more notifications before the notifications are sent:


You can view JSON for notifications by viewing their entity entries in the Data section of your application.

  • In the admin portal, click Data, then click the /notifications collection.

You can also view notification data in the message history.

  1. In the admin portal, click Push, then click Message History.
  2. Locate the notification for which you want to view data, then click its view details link.

Canceling sent notifications

You can cancel a notification that's already in progress by doing the following:

curl -X PUT "https://api.usergrid.com/my-org/sandbox/notifications/<notification-uuid>" -d '{"canceled": true}'

Deleting unsent notifications

curl -X DELETE "https://api.usergrid.com/<you-org>/<app>/notifications/<notification-uuid>"
  1. In the admin portal, click Push, then Message History.
  2. On the Message History page, click Scheduled.
  3. In the list of scheduled messages, locate the message you want to delete.
  4. In the top area of the message item, click the delete link.

Getting receipts

After sending a notification, the BaaS generates a receipt entity that contains details about the notification. Receipts show details such as timestamps, payloads sent, and the receipt endpoints.

For information about what's contained in a receipt, see Notifier, Receipt, and Notification. Use the following endpoints to get receipts.

To get one or more receipts:


To get receipts associated with one or more devices:


To get receipts for one or more notifications. For example, get receipts for notifications that had errors.


Notification endpoints

The /notifications endpoints let you create, schedule, cancel, and delete notifications. You can also use the following endpoints to accomplish the same actions for specific groups, users, devices, or any combination thereof.

Base URL: https://api.usergrid.com/my-org/my-app

  • /groups/*/notifications
  • /groups/*/users/*/notifications
  • /groups/*/users/*/devices/*/notifications
  • /users/*/notifications
  • /users/*/devices/*/notifications
  • /devices/*/notifications


On IOS Apple Push Notifications (APNs) has a feedback service that maintains a per-application list of devices for which there were failed-delivery attempts (that is, APNs was unable to deliver a push notification to an application on a device). Periodically, the provider should connect with the feedback service to see what devices have persistent failures so that it can refrain from sending push notifications to them.

Do you provide an API to get this list or should we build it from devices not present in the Receipt entity ?

Thanks !


Hi Bernard

If the Feedback service returns a device error, it will be logged in the receipt entity. There are two properties "errorMessage" and "errorCode" that you can reference for this, if an error occurs.

Thanks for helping us improve the push notification documentation!

Are sounds enabled in push notifictions?
Usually I'd expect an option of "sound":"" or "sound":"default" ?

Yes, they are. Here's an iOS sample:

"alert":"You pushed the button!"

Hi. Can i use
"curl -X POST https://api.usergrid.com///devices/*/notifications -d '{"payloads":{:{title:"some_title","message":"some_message"}}}'"
instead of
"curl -X POST https://api.usergrid.com///devices/*/notifications -d '{"payloads":{:}}'"?

Hi Farit -- My apologies for taking so long to respond. "title" doesn't appear to be supported as a key in the payload. What are you trying to accomplish? (Also, though your examples don't include them, I'm assuming you'd have org name, app name, and notifier name in your request.)

Actually, after playing with this a bit, I've discovered that you should be able to format a request this way:

curl -X POST https://api.usergrid.com/my_org/my_app/devices/*/notifications -d '{"payloads":{"notifier_name":{"title":"some title","message":"Hey!"}}}'

I am trying to use your js example of sending push notification, but as I need to send push to all devices I change the devicePath:
var devicePath = "devices/"+client.getDeviceUUID()+"/notifications";
var devicePath = "devices/*/notifications";

Calling client.sendPushToDevice then succeeds but show Failed status in the Message History and no messages delivered. Can you please help?

The documentation is really confusing around the * character that shows up in the routes. After some experimentation, I found that if I make a request to: /{org}/{app}/devices/*/notifications
as per the documentation examples, the API call succeeds with a 200, but when I look up the notification it has:
"errorMessage" : "java.lang.NullPointerException",
"state" : "FAILED"

I also tried using: /{org}/{app}/devices/notifications
which also didn't work.

So it appears that the documentation is just wrong. I captured the traffic from the UI page for sending notifications and found that it does something completely different: /{org}/{app}/devices;ql=/notifications
which works.

Please fix your documentation; even if the * character did work, it's really confusing. Also, the docs for all your APIs are absolutely terrible at defining error responses. And the APIs are inconsistent in which HTTP status codes they give anyway...

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.