Skip to content
User guides Support Request demo Sign in
Pushwoosh.com

Device API

registerDevice

Section titled “registerDevice”

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

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “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
  • 14 – Email
  • 17 – Huawei
  • 18 – SMS
  • 21 – WhatsApp

Registering email devices

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

unregisterDevice

Section titled “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 headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “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

Section titled “setTags”

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

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “getTags”

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

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “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

Section titled “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 headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “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

Section titled “applicationOpen”

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

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “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

Section titled “pushStat”

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

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “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

Section titled “messageDeliveryEvent”

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

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

Request headers

Section titled “Request headers”
NameRequiredValueDescription
AuthorizationYesToken XXXXAPI Device Token to access Device API. Replace XXXX with your actual Device API token.

Request body

Section titled “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)
  }
}