Audience API

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

Parameter	Type	Required	Description
application	string	Yes	The application code for your Pushwoosh account.
auth	string	Yes	The API authentication token.
devices	array	Yes	An 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

Parameter	Type	Required	Description
hwid	string	Yes	The hardware ID or unique identifier for the device.
push_token	string	Yes	Push token for the device.
platform	integer	Yes	The platform identifier. Learn more
list_operator	string	No	Determines 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.
tags	object	No	Custom 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"
}

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

Parameter	Type	Required	Description
request_id	string	Yes	The request ID returned by the POST request.
detailed	boolean	No	If 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"
    }
  ]
}

bulkSetTags

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

Sets tag values for the list of devices.

Request Body

Name	Type	Description
application*	String	Pushwoosh app code.
auth*	String	API access token from Pushwoosh Control Panel.
create_missing_tags	Boolean	If true, missing tags are created automatically.
devices*	Object	Array of devices.
devices.hwid	String	Can be used to identify a device instead of user_id or push_token
devices.user_id	String	Can be used to identify a user instead of hwid or push_token
devices.push_token	String	Can be used to identify a device instead of hwid or user_id
devices.list_operator	String	Defines how to set values for tags of the list type: set, append, or remove
devices.tags*	Object	Values to set for the tags specified.

OK
Error

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

{
  "message": "invalid request"
}

{
  "application": "application code",   // required. Pushwoosh app code
  "auth": "Pushwoosh auth token",      // required. API access token from Pushwoosh Control Panel
  "create_missing_tags": false,        // optional. Should automatically create missing tags
  "devices": [{                        // required. Array of devices
    "hwid": "device hwid",             // optional. Can be used to identify a device instead of
                                       //           "user_id" or "push_token".
    "user_id": "user ID",              // optional. Can be used to identify a user instead of "hwid" or "push_token".
    "push_token": "device push token", // optional. Can be used to identify a device instead of "hwid" or "user_id".
    "list_operator": "set",            // required. For list tags. Defines how to set values for
                                       //           tags of the list type: set, append, or remove
    "tags": {                          // required. Values to set for the tags specified.
      "tag_name": "tagvalue",          //           use correct value type
      "tag_name2": "tagvalue2"
    }
  }]
}

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

bulkSetTags status

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

Returns the status of /bulkSetTags operation

Path Parameters

Name	Type	Description
request_id	String	request id from previous /bulkSetTags call

Query Parameters

Name	Type	Description
detailed	Boolean	(true/false) whether to return detailed per-device info

{
  "request_id": "id of the request",
  "status": "Completed",          // also "Pending", "Failed"
  "progress": 100,                // jobs progress 0-100
  "devices_success": 100,         // good devices
  "devices_not_found": 0,         // devices not found in Pushwoosh
  "devices_failed": 0,            // errored
  "devices": [{                   // device report (only in detailed = true)
    "hwid": "device hwid",
    "status": "done",             // also "failed", "not found"
    "tags": {
      "tagName": "ok",
      "tagName2": "tag not found",
      "tagName3": "wrong value. expect :string",
    }
  }]
}