Cloudfive Push API Reference

Terminology. Because words are important

Cloudfive Push lets you identify users however you want -- as long as the identifier you choose is unique for all of your users. This is often the database id of your users, their unique username, or even their email but you can use whatever you want. We'll refer to this choice as the

user identifier.

Specifying API Version

Specifying the version of the API you want is as easy as setting the Accept header to "application/vnd.cloudfive.v[VERSION]"
Currently there is only one version: 1.
The default version is 1 so you are not required to include this header. However, in the future the default will be set to the newest version, so we recommend setting this so that a new version release doesn't break your API consumers.


Cloudfive Push will send json with an error attribute containing the error. For example,

  "success": false,
  "error": "Missing parameter: api_key"

Error Messages

Error message Reason
Missing parameter:
You need to include the specified parameter
Invalid API key You're sending up an API key that does not exist anymore. This can happen if you recently revoked your old key and regenerated a new one.
Cannot deliver to android devices because app does not have a GCM API key You need to set your Google Cloud Messaging API key on your app's push configuration page.
Cannot deliver to iOS devices because app does not have a development APNs certificate You need to set your development APNs certificate on your app's push configuration page.
Cannot deliver to iOS devices because app does not have a production APNs certificate You need to set your production APNs certificate on your app's push configuration page.
data is invalid JSON You have a malformed data param.
No devices found with given parameters We couldn't find any devices registered with the given user identifiers or any at all if you specified audience=broadcast. Make sure you are registering your users properly and that you are using the correct user identifiers
Invalid parameters, please include user_identifier, user_identifiers or audience=broadcast You must send one of the three params above.

Error Codes

Error code Reason
200 - OK Everything worked! Congrats!
400 - Bad Request Often missing a required parameter. The response should tell you which parameter you're missing.
422 - Unprocessable Entity Parameters were valid but request failed. This can happen if your API key is invalid, if there are no devices registered to which to send your push notification, if your GCM API key or APNs certificates aren't present or your data json payload is malformed.
50* Cloudfive Push server error. We should be up and running shortly.
Get an error that's not documented here? Please let us know!


To authenticate with Cloudfive Push, the api_key must be sent as a parameter when making the request.

  "api_key": "your_api_key"

Sending a notification

Available endpoints

GET /push/notify
POST /push/notify
POST /push

Specifying users to receive your notification

There are three ways to specify to which users to send your notification: broadcasting which sends your message to every user of your app, specifying a single user identifier or finally specifying an array of user identifiers. Let's see examples of each of these options.

// Send to everyone
  "audience": "broadcast",
  "alert": "Hello from Cloudfive",
  "api_key": "your_api_key"
// Send to user 42
  "user_identifier": 42,
  "alert": "Hello from Cloudfive",
  "api_key": "your_api_key"
// Send to users 1, 2, 3, 5 and 8
  "user_identifiers": [1, 2, 3, 5, 8],
  "alert": "Hello from Cloudfive",
  "api_key": "your_api_key"

Push Parameters

Name Type / Possible Values Meaning Required
user_identifier, user_identifiers, audience String, Array or "broadcast", respectively To whom to send your notification. Can either be a single user, multiple users or everyone, respectively. Yes. At least one of these must be given
alert String This key needs to be set in order for cloud five to display anything to the user. This includes appearing in the notificication center in iOS and the notification drawer in iOS. This should be a short message No.
message String A longer message that will be displayed alongside the alert when the alert notification is displayed. This happens right away if the app is running when the notification is recieved, otherwise it is displayed when the user interacts with the notification. If set without the alert property present, the message will not be displayed automatically. No
badge Integer iOS only. Sets the numeric badge count on the app's home screen icon. No
push_at Datetime String When to send the push notification. If not supplied, the notification is sent immediately. No
data Hash An arbitrary JSON hash that will be passed down to the client app and be made available in a custom handler function. No
aps_environment String iOS only. Default is "production". Specify which aps-environment to use for delivering to Apple devices. Possible values are "development" and "production". You can use the "development" setting if you ahve configured development certificates to test cloud five integration locally. For normal usage this should be set to "production" or omitted. No
content_available Boolean iOS only. Default is false. If set to true, Cloudfive will set the apple "content-available" property to "1" which will enable the Apple background-fetch process. This requires a custom implementation on the iOS client and should normally be omitted. No
Something missing or incorrect? Please let us know!