# Audience API

## bulkSetTags

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

Sets tag values for the list of devices.

<Aside type="caution" title="Important">
  When using the `bulkSetTags` method, ensure that tag values are set for a minimum of 50 devices. To set tags for a single device, use the [`setTags`](/developer/api-reference/device-api/#settags) method.
</Aside>

#### Request Body

| Name                                           | Type    | Description                                                                 |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| application\*  | String  | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                                     |
| auth\*         | String  | [API access token](/developer/api-reference/api-identifiers/#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. [Learn more](/developer/api-reference/api-identifiers/#hardware-id)         |
| devices.user\_id                               | String  | Can be used to identify a user instead of hwid or push\_token. [Learn more](/developer/api-reference/api-identifiers/#user-id)               |
| devices.push\_token                            | String  | Can be used to identify a device instead of hwid or user\_id. [Learn more](/developer/api-reference/api-identifiers/#push-token)                |
| devices.list\_operator                         | String  | Defines how to set values for [tags](/developer/api-reference/api-identifiers/#tag) of the list type: set, append, or remove |
| devices.tags\* | Object  | Values to set for the tags specified.                                       |

<Tabs>
  <TabItem label="OK">
    ```json
    {
      "request_id": "request_id to use in GET method to obtain job status",
      "status": "Pending"
    }
    ```
  </TabItem>

  <TabItem label="Error">
    ```json
    {
      "message": "invalid request"
    }
    ```
  </TabItem>
</Tabs>


```json title="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"
    }
  }]
}

```

```json title="Response:"
{
  "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 |

```json title="Response:"
{
  "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"
    }
  }]
}

```

## 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 body parameters

| Parameter | Type | Required | Description |
| :---- | ----- | ----- | ----- |
| application | string | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |
| auth | string | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-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](/developer/api-reference/api-identifiers/#hardware-id) or unique identifier for the device.                                           |
| push_token    | string | Yes      | [Push token](/developer/api-reference/api-identifiers/#push-token) for the device.                                                                     |
| platform      | integer| Yes      | The platform identifier. [Learn more](/developer/api-reference/messages-api/api-prerequisites/#platforms) |
| list_operator | string | No       | Determines the action for list-type tags: <br/> - **"append"**: Add the specified value to the tag list. <br/> - **"remove"**: Remove the specified value from the tag list. <br/> **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](/developer/api-reference/api-identifiers/#tag) assigned to the device. Tags are key-value pairs used for segmentation.            |



#### Request example

```json
{
  "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.

```json
{
  "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

```json
{
  "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"
    }
  ]
}

```

## bulkUnregisterDevice

Unregisters multiple devices from Pushwoosh in a single request.

`POST` `https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice`

### Request body parameters

| Parameter | Type | Required | Description |
| :---- | ----- | ----- | ----- |
| application | string | Yes | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code) |
| auth | string | Yes | [API access token](/developer/api-reference/api-identifiers/#api-access-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. [Learn more](/developer/api-reference/api-identifiers/#hardware-id)                                          |



#### Request example

```json
{
  "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).
  },
  {
    "hwid": "device hwid 2",           // required. Unique identifier for the second device.
  },
  {
    "hwid": "device hwid 3",           // required. Unique identifier for the third device.
  }]
}

```

### Response

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

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

```

## bulkUnregisterDevice status

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

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice/{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 unregistered device. |


#### Example response

```json
{
  "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"
    }
  ]
}

```