API Version 1

Authentication & Headers

You authenticate to Pushbots API by providing Application ID in request headers.
Header Description
Content-Type Set to application/json *.
X-PUSHBOTS-APPID Pushbots Application ID. *
X-PUSHBOTS-SECRET Pushbots Application secret, should be used with Push API only.
* Required

Rate Limits

API calls are subject to rate limiting. Exceeding any rate limits will result in all endpoints returning a status code of 429 (Too Many Requests). Rate limits are per user per app.


Errors

Errors are returned using standard HTTP error code syntax. Any additional info is included in the body of the return call, JSON-formatted. Error codes not listed here are in the REST API methods listed below.


Standard API errors

Code Description
400 Bad input parameter/JSON. Error message should indicate which one and why e.g. {"code":"InvalidHeader","message":"Authentication headers not found."} , {"code:"", "BadDigest":"Please contact support for more details, supportId #12345"}, {"code":"InvalidContent","message":"Invalid JSON: ."}
401 Authentication headers are unauthorized. e.g. {"code":"InvalidCredentials","message":"Application ID and/or Secret unauthorized."}
405 Request method not expected (generally should be GET or POST) e.g. {"code":"MethodNotAllowedError","message":"GET is not allowed"}
409 Request could not be processed because of a missing parameter or a conflict. Error message should indicate which one and why e.g.{"code":"MissingParameter","message":"Notification message parameter is required."}
429 Too Many Requests.
507 User is over API requests quota.
5xx Pushbots Server error, check server status.

Devices

Register Device

PUT https://api.pushbots.com/deviceToken

Register device token of the app in the database first time , and update it with every launch of the app , device data will be updated if registered already

Paremeters (JSON Payload)

token Required (String)

the unique token retrieved by your app;device token of the iOS app or RegID of the android App and usually it's managed using SDK

platform Required (String)

0 for iOS.
1 for Android

lat Optional (String)

Location latitude e.g. 33.7489

lng Optional (String)

Location longitude e.g. -84.3789

active Optional (Array)

Array of notification Types linked to the device e.g. ["Subscriptions" , "Followers"]

tag Optional (Array)

Array of tags associated with the deviceToken , if empty array that'll remove any associated tags e.g. ["Culture" , "EGYPT"]

alias Optional (String)

alias to access device data without tokens and it must be unique for every app e.g. "username" , "email" ..etc

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "token" : String ,  "platform" : String ,  "lat" : String ,  "lng" : String ,  "active" : Array ,  "tag" : Array ,  "alias" : String  }' \
https://api.pushbots.com/deviceToken

Register Multiple Devices

PUT https://api.pushbots.com/deviceToken/batch

Register multiple devices up to 500 Device per request

Paremeters (JSON Payload)

tokens Required (Array)

Array of devices tokens to be added to database, up to 500 device per request

platform Required (String)

0 for iOS.
1 for Android

tags Optional (Array)

Array of tags associated with all imported devices e.g. ["Culture" , "USA"]

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "tokens" : Array ,  "platform" : String ,  "tags" : Array  }' \
https://api.pushbots.com/deviceToken/batch

unRegister Device

PUT https://api.pushbots.com/deviceToken/del

unRegister device token of the app from the database

Paremeters (JSON Payload)

token Required (String)

the unique token retrieved by your app;device token of the iOS app or RegID of the android App and usually it's managed using SDK

platform Required (String)

0 for iOS.
1 for Android

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "token" : String ,  "platform" : String  }' \
https://api.pushbots.com/deviceToken/del

Alias

PUT https://api.pushbots.com/alias

Add/update alias of a device .

Paremeters (JSON Payload)

platform Required (String)

0 for iOS.
1 for Android

token Optional (String)

the unique token retrieved by your app;device token of the iOS app or RegID of the android App and usually it's managed using SDK

alias Optional (String)

alias to access device data without tokens and it must be unique for every app e.g. "username" , "email" ..etc

current_alias Optional (String)

Set this parameter in case you want to update existing alias

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "platform" : String ,  "token" : String ,  "alias" : String ,  "current_alias" : String  }' \
https://api.pushbots.com/alias

Tag Device

PUT https://api.pushbots.com/tag

Tag a device with its token through SDK or Alias through your backend

Paremeters (JSON Payload)

platform Required (String)

0 for iOS.
1 for Android

tag Required (String)

"Tag" to be Added

token Optional (String)

the unique token retrieved by your app;device token of the iOS app or RegID of the android App and usually it's managed using SDK

Alias Optional (String)

alias to access device data without tokens and it must be unique for every app e.g. "username" , "email" ..etc

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "platform" : String ,  "tag" : String ,  "token" : String ,  "Alias" : String  }' \
https://api.pushbots.com/tag

unTag Device

PUT https://api.pushbots.com/tag/del

unTag a device its token through SDK or Alias through your backend

Paremeters (JSON Payload)

platform Required (String)

0 for iOS.
1 for Android

tag Required (String)

"Tag" to be removed

token Optional (String)

the unique token retrieved by your app;device token of the iOS app or RegID of the android App and usually it's managed using SDK

Alias Optional (String)

alias to access device data without tokens and it must be unique for every app e.g. "username" , "email" ..etc

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "platform" : String ,  "tag" : String ,  "token" : String ,  "Alias" : String  }' \
https://api.pushbots.com/tag/del

Device Location

PUT https://api.pushbots.com/geo

Add/update location of a device

Paremeters (JSON Payload)

platform Required (String)

0 for iOS.
1 for Android

token Required (String)

the unique token retrieved by your app;device token of the iOS app or RegID of the android App and usually it's managed using SDK

lat Required (String)

Location latitude e.g. 33.7489

lng Required (String)

Location longitude e.g. -84.3789

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "platform" : String ,  "token" : String ,  "lat" : String ,  "lng" : String  }' \
https://api.pushbots.com/geo

Device Info

GET https://api.pushbots.com/deviceToken/one

Device Details

Response

Example Request

curl -X GET \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
https://api.pushbots.com/deviceToken/one

Push

Push to Single Device

POST https://api.pushbots.com/push/one

Push a notification to a single device

Paremeters (JSON Payload)

platform Required (String)

0 for iOS.
1 for Android

token Required (String)

Device Token

msg Required (String)

Notification Message

sound Required (String)

Notification Sound

badge Required (String)

Notification Badge number

payload Optional (JSON)

Custom fields

Response

Example Request

curl -X POST \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "platform" : String ,  "token" : String ,  "msg" : String ,  "sound" : String ,  "badge" : String ,  "payload" : JSON  }' \
https://api.pushbots.com/push/one

Batch

POST https://api.pushbots.com/push/all/

Push a notification to Devices under certain conditions .

Paremeters (JSON Payload)

platform Optional (Array)

0 for iOS.
1 for Android e.g. [0,1] to push to Android and iOS.

msg Optional (String)

Notification Message

sound Optional (String)

Notification Sound

badge Optional (String)

Notification Badge number

tags Required (Array)

Send notifications by tags

except_tags Required (Array)

Array of tags to exclude

active Required (Array)

Array of Notification Types

except_active Required (Array)

Array of Notification Types to exclude

alias Required (String)

alias to access device data without tokens and it must be unique for every app e.g. "username" , "email" ..etc

except_alias Required (String)

Alias to exclude

payload Required (JSON)

Custom fields

Response

Example Request

curl -X POST \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "platform" : Array ,  "msg" : String ,  "sound" : String ,  "badge" : String   "tags" : Array ,  "except_tags" : Array ,  "active" : Array ,  "except_active" : Array ,  "alias" : String ,  "except_alias" : String ,  "payload" : JSON , }' \
https://api.pushbots.com/push/all/

Badge

PUT https://api.pushbots.com/badge

Update device Badge

Paremeters (JSON Payload)

token Required (String)

the unique token retrieved by your app;device token of the iOS app or RegID of the android App and usually it's managed using SDK

platform Required (String)

0 for iOS.
1 for Android

setbadgecount Required (int)

New Badge count

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "token" : String ,  "platform" : String ,  "setbadgecount" : int  }' \
https://api.pushbots.com/badge

Get Push analytics

GET https://api.pushbots.com/analytics

Get Push analytics of a single Application

Response

Example Request

curl -X GET \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
https://api.pushbots.com/analytics

Analytics

Record Analytics

PUT https://api.pushbots.com/stats

Record Opened Push Analytics.

Paremeters (JSON Payload)

platform Required (String)

0 for iOS.
1 for Android

Response

Example Request

curl -X PUT \
-H "x-pushbots-appid: 54cc0a511d0ab13c0528b459d" \
-H "x-pushbots-secret: 1444fe8be3324ff7128f25aa18cdee12" \
-H "Content-Type: application/json" \
-d '{ "platform" : String  }' \
https://api.pushbots.com/stats