Skip to content

Device API

registerDevice

POST https://api.pushwoosh.com/json/1.3/registerDevice

Called internally from the SDK. Registers device for the application.

Request Body

NameTypeDescription
application*stringPushwoosh application code.
push_tokenstringPush token for the device.
languagestringLanguage locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard.
hwid*stringUnique string to identify the device (IDFV on iOS, randomly generated value on Android).
timezoneintegerTimezone offset in seconds for the device.
device_type*integerDevice type. See possible values below.
emailstringEmail address to register (use for email users instead of HWID and push token).
tagsobjectTag values to assign to the device registered.
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request": {
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"push_token": "dec301908b9ba8XXXXX57a58e40f96f5XXXXX2068674f5XXXXa25cdc250a2a41", // optional.
"hwid": "1CA6XXXXX-8DAC-XXXXX-XXXXX-B756288B6D3C", // required. Hardware device ID
"idfa": "AEBE52E7-0XXXXX-455A-XXXXX-E57283966239", // optional.
"timezone": 3600, // optional. Offset in seconds
"device_type": 1, // required. See the possible values below. For emails,
// use the "emails" params as described below.
"email": "email_address@domain.com", // use instead of "hwid" and "push_token" to register
// the email address for your email project
"language": "en", // optional. ISO 639-1|639-2 language code
"userId": "Alex", // optional.
"tags": { // optional. Tag values to set for the device registered
"StringTag": "string value",
"IntegerTag": 42,
"ListTag": ["string1", "string2"], // sets the list of values for Tags of List type
"DateTag": "2024-10-02 22:11", // note the time should be in UTC
"BooleanTag": true // valid values are: true, false
},
// system tags, optionals
"app_version": "1.2.3",
"device_model": "Samsung SM-G355H",
"os_version": "2.3",
// optional encryption keys for chrome/firefox
"public_key": "BNmDO4BTKEMJqaqprTf7t/HBXXXXX/orcXXXXX/scS5CFP6XXXXXHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
"auth_token": "RlRmCXXXXX/s7XXXXXjKFzoQ==",
// optional FCM keys for Chrome (for XMPP)
"fcm_token": "BNmDO4BTKEMJXXXXXprTf7t/XXXXXBQ/orXXXXXc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
"fcm_push_set": "RlXXXXXGM/s7XXXXXjKFzoQ=="
}
}

Possible device types:

  • 1 – iOS
  • 3 – Android
  • 7 – Mac OS X
  • 8 – Windows
  • 9 – Amazon
  • 10 – Safari
  • 11 – Chrome
  • 12 – Firefox
  • 17 – Huawei
  • 18 – SMS
  • 21 – WhatsApp

Registering email devices

To register a email subscriber for your app, send the "email": "email_address@domain.com" param in your /registerDevice or /registerEmail request as follows:

Request example

{
"request":{
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"email": "email_address@domain.com", // required. Email address to register for your email project
"language": "en", // optional. ISO 639-1|639-2 language code
"userId": "Alex", // optional.
"tags": { // optional. Tag values to set for the device registered
"StringTag": "string value",
"IntegerTag": 42,
"ListTag": ["string1", "string2"], // sets the list of values for Tags of List type
"DateTag": "2024-10-02 22:11", // note the time should be in UTC
"BooleanTag": true // valid values are: true, false
}
}
}

Registering WhatsApp devices

To register a WhatsApp device for your app, follow these guidelines:

  • hwid: Ensure this field includes the whatsapp: prefix followed by the phone number in E.164 format (e.g., whatsapp:+0000000000). The phone number must be valid, which Pushwoosh will verify.

  • Push token: A push token is not required, as hwid will automatically function as the push token.

  • device_type: Set this field to 21 to specify WhatsApp as the platform.

Request example

{
"request": {
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "whatsapp:+0000000000", // required. WhatsApp prefix and valid phone number
"timezone": 3600, // optional. Time offset in seconds
"device_type": 21, // required. WhatsApp device type is 21
"language": "en", // optional. ISO 639-1|639-2 language code
"userId": "Alex", // optional. User identifier
"tags": { // optional. Tag values for custom segmentation
"StringTag": "string value",
"IntegerTag": 42,
"ListTag": ["string1", "string2"],
"DateTag": "2024-10-02 22:11", // UTC format
"BooleanTag": true
},
"app_version": "1.2.3", // optional. Application version
"device_model": "Samsung SM-G355H", // optional. Device model
"os_version": "2.3" // optional. Operating system version
}
}

Registering SMS devices

To register an SMS device for your app, follow these guidelines:

  • hwid: Ensure this field includes the phone number in E.164 format (e.g., +0000000000). The phone number must be valid, which Pushwoosh will verify.

  • Push token: A push token is not required, as hwid will automatically function as the push token.

  • device_type: Set this required field to 18 to designate SMS as the platform.

Request example

{
"request": {
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "+0000000000", // required. Valid phone number in E.164 format
"timezone": 3600, // optional. Time offset in seconds
"device_type": 18, // required. SMS device type is 18
"language": "en", // optional. ISO 639-1|639-2 language code
"userId": "Alex", // optional. User identifier
"tags": { // optional. Tag values for custom segmentation
"StringTag": "string value",
"IntegerTag": 42,
"ListTag": ["string1", "string2"],
"DateTag": "2024-10-02 22:11", // UTC format
"BooleanTag": true
},
"app_version": "1.2.3", // optional. Application version
"device_model": "Samsung SM-G355H", // optional. Device model
"os_version": "2.3" // optional. Operating system version
}
}

Status codes:

HTTP Status codestatus_codeDescription
200200Device successfully registered
200210Argument error. See status_message for more info.
400N/AMalformed request string
500500Internal error

bulkRegisterDevice

Registers multiple devices in Pushwoosh in a single request. It also allows specifying various tags for each device.

POST https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice

Request parameters

ParameterTypeRequiredDescription
applicationstringYesThe application code for your Pushwoosh account.
authstringYesThe API authentication token.
devicesarrayYesAn array of device objects. Each object represents a device and its associated data. See details in the Device object parameters table below.

Device object parameters

ParameterTypeRequiredDescription
hwidstringYesThe hardware ID or unique identifier for the device.
push_tokenstringYesPush token for the device.
platformintegerYesThe platform identifier. Learn more
list_operatorstringNoDetermines the action for list-type tags:
- “append”: Add the specified value to the tag list.
- “remove”: Remove the specified value from the tag list.
Note: If the list_operator parameter is not specified, all existing values in the tag list will be replaced with the provided values.
tagsobjectNoCustom tags assigned to the device. Tags are key-value pairs used for segmentation.

Request example

{
"application": "application code", // required. Pushwoosh app code
"auth": "Pushwoosh auth token", // required. API access token from Pushwoosh Control Panel
"devices": [{ // required. Array of devices
"hwid": "device hwid", // required. Unique identifier for the device (can be an email).
"push_token": "device push token", // required. Push notification token for the device.
"platform": 14, // required. Device platform (e.g., 14 for email).
"list_operator": "append", // optional. For list tags. Adds or removes the specified value(s) from the tag of list type.
"tags": { // optional. Values to set for the specified tags.
"language": "en", // use correct value type.
"CSV_Import": "summer_camp"
}
},
{
"hwid": "device hwid 2", // required. Unique identifier for the second device.
"push_token": "device push token 2", // required. Push notification token for the device.
"platform": 14, // required. Device platform.
"list_operator": "remove", // optional. Adds or removes values from tags of the list type.
"tags": { // optional. Values to remove from the specified tags.
"language": "en",
"CSV_Import": "summer_camp2"
}
},
{
"hwid": "device hwid 3", // required. Unique identifier for the third device.
"push_token": "device push token 3", // required. Push notification token for the device.
"platform": 14, // required. Device platform.
"tags": { // optional. Values to set for the specified tags.
"language": "en",
"CSV_Import": "summer_camp3"
}
}]
}

Response

The method responds with an operation ID, which can be used to track the status and results of the bulk registration process.

{
"request_id": "request_id to use in GET method to obtain job status",
"status": "Pending"
}

Checking bulkRegisterDevice status

You can check the status of a bulk registration process by making the following GET request:

GET https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice/{request_id}?detailed=true

ParameterTypeRequiredDescription
request_idstringYesThe request ID returned by the POST request.
detailedbooleanNoIf set to true, the response includes detailed results for each registered device.

Example response

{
"request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
"status": "Completed",
"progress": 100,
"devices_success": 4,
"devices": [
{
"hwid": "user1@example.com",
"status": "done"
},
{
"hwid": "user2@example.com",
"status": "done"
},
{
"hwid": "user3@example.com",
"status": "done"
},
{
"hwid": "invalid_email@example.com",
"status": "failed"
}
]
}

unregisterDevice

POST https://go.pushwoosh.com/json/1.3/unregisterDevice

Removes the device’s push token. The unregistered device is still counted in Total Devices and can be reached with In-Apps. Called internally from the SDK.

Request Body

NameTypeDescription
application*stringPushwoosh application code.
hwid*stringHardware device ID used in /registerDevice request.
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request": {
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "8f65b16XXXXXe7a6beceXXXXX530fb2" // required. Hardware device ID used in /registerDevice API
}
}

Status codes:

HTTP Status codestatus_codeDescription
200200Device successfully unsubscribed
200210Argument error. See status_message for more info.
400N/AMalformed request string
500500Internal error

setTags

POST https://go.pushwoosh.com/json/1.3/setTags

Sets tags values for the device. Called from the SDK.

Request Body

NameTypeDescription
application*stringPushwoosh application code.
hwid*stringHardware device ID used in /registerDevice request.
tags*objectJSON object of tags to set, send “null” to remove the value.
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request":{
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "8f65b16XXXXXe7a6becXXXXXe1530fb2", // required. Hardware device ID used in /registerDevice API
"tags": { // required.
"StringTag": "string value",
"IntegerTag": 42,
"ListTag": ["string1", "string2"], // sets the list of values for Tags of List type
"DateTag": "2024-10-02 22:11", // note the time is in UTC
"BooleanTag": true // valid values are - true, false
}
}
}

Increment Integer tag values

To increment a value of the Integer Tag, use the operation parameter with the “increment” value as follows:

{
"request":{
"application": "12345-67890", // required. Pushwoosh application code
"hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. hardware device ID used in /registerDevice API
"tags": { // required.
"Level": { // Tag name
"operation": "increment", // overwrites the integer tag in increments of the following value
"value": 1 // increment for the tag value
}
}
}
}

Decrement Integer tag values

To decrement, use the negative numbers as the value for the “increment” operation (-1, -2, -3,-n):

{
"request":{
"application": "12345-67890", // required. Pushwoosh application code
"hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API
"tags": { // required
"Level": { // Tag name
"operation": "increment", // overwrites the integer tag in decrement of the following value
"value": -1 // decrement for the tag value
}
}
}
}

Append List tag values

To extend the List Tag with new values, use the operation parameter with the “append” value as follows:

Example
{
"request": {
"hwid": "3d124a79XXXXf189XXXX7dfd9XXXXafd", // required. Hardware device ID used in /registerDevice API
"application": "6XXXX-XXXX3", // required. Pushwoosh application code
"tags": { // required.
"ListTag": { // Tag name
"operation": "append", // appends following values to the Tag's list of values
"value": [ // values to append
"tag2",
"tag3"
]
}
}
}
}

Remove List tag values

To remove some values from the List Tag, use the “remove” operation as follows:

{
"request":{
"application": "12345-67890", // required. Pushwoosh application code
"hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API
"tags": { // required.
"In-App Product": { // Tag name
"operation": "remove", // removes the following values from the list tag
"value": "outwear_02" // value or values to remove
}
}
}
}

Set tags by UserID

To set tags for all devices associated to a particular User ID, use the “userId” parameter instead of “hwid”.

Example
{
"request":{
"application": "AAAAA-BBBBB", // Pushwoosh app code
"userId": "some_user", // user ID you'd like to set tags for
"tags": { // tags and values to set
"Language": "es"
}
}
}

Status codes:

HTTP Status codestatus_codeDescription
200200Tags have been successfully set
200210Argument error. See status_message for more info.
400N/AMalformed request string
500500Internal error

getTags

POST https://go.pushwoosh.com/json/1.3/getTags

Retrieves a list of tags with corresponding values for the specific device.

Request Body

NameTypeDescription
application*stringPushwoosh application code.
userIdstringUser identifier to be used instead of “hwid”. If used together with a “hwid”, the “hwid” prevails.
hwidstringHardware device ID used in /registerDevice request.
{
"status_code": 200,
"status_message": "OK",
"response": {
"result": {
"Language": "fr"
}
}
}
Example
{
"request":{
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "HWID", // optional. Hardware device ID used in /registerDevice API
"userId": "USER_ID" // optional. Can be used instead of "hwid" to retrieve tags for a specific user
}
}

setBadge

POST https://api.pushwoosh.com/json/1.3/setBadge

Sends current badge value for a device to Pushwoosh. Called internally from the SDK.

Request Body

NameTypeDescription
application*stringPushwoosh application code.
hwid*stringHardware device ID used in /registerDevice request.
badge*integerCurrent badge on the application.
{
"status_code": 200,
"status_message": "OK"
}
Example
{
"request":{
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "8f65b16dXXXXe7a6XXXX9614XXXX0fb2", // required. Hardware device ID used in /registerDevice API
"badge": 4 // required. Current badge on the application
}
}

Called from the SDK internally. Sends current badge value for a device to Pushwoosh. This happens internally when app changes badge value on iOS device. Allows auto-incrementing badges to work properly.

applicationOpen

POST https://api.pushwoosh.com/json/1.3/applicationOpen

Registers an app open event. Called internally from the SDK.

Request Body

NameTypeDescription
application*stringPushwoosh application code.
hwid*stringHardware device ID used in /registerDevice request.
{
"status_code": 200,
"status_message": "OK"
}
Example
{
"request": {
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "8f65b16dXXXXe7a6XXXX9614eXXXXfb2" // required. Hardware device ID used in /registerDevice API
}
}

pushStat

POST https://api.pushwoosh.com/json/1.3/pushStat

Registers a push open event. Called internally from the SDK.

Request Body

NameTypeDescription
application*stringPushwoosh application code.
hwid*stringHardware device ID used in /registerDevice request.
userIdstringThe user ID to associate with the push open event.
hashstringHash tag received in push notification (“p” parameter of the push payload).
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request": {
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // required. Hardware device ID used in /registerDevice API
"userId": "USER012345", // optional. The user id to associate with the push open event
"hash": "HASH_TAG" // optional. Hash tag received in push notification
// ("p" parameter in the push payload)
}
}

messageDeliveryEvent

POST https://api.pushwoosh.com/json/1.3/messageDeliveryEvent

Registers push delivery event for the device. Called internally from the SDK.

Request Body

NameTypeDescription
application*stringPushwoosh application code.
hwid*stringHardware device ID used in /registerDevice request.
hashstringHash tag received in push notification (“p” parameter of the push payload).
{
"status_code": 200,
"status_message": "OK",
"response": null
}
Example
{
"request": {
"application": "XXXXX-XXXXX", // required. Pushwoosh application code
"hwid": "8f65b16dfXXXX7a6bece9XXXX1530fb2", // required. Hardware device ID used in /registerDevice API
"hash": "HASH_TAG" // optional. Hash tag received in push notification
// ("p" parameter in the push payload)
}
}