Segmentation (Filters) API

createFilter

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

Creates a new filter.

Request Body

Name	Required	Type	Description
auth*	Yes	string	API access token from Pushwoosh Control Panel.
name*	Yes	string	Filter name.
filter_expression*	Yes	string	Expression constructed according to the rules of the Segmentation language. Example: `T(“City”, eq, “Madrid”)` to segment users whose city is Madrid.
application	No	string	Pushwoosh application code. This parameter is usable only with High-Speed Setup; omit otherwise.
expiration_date	No	string	Filter expiry. The filter will be automatically deleted on a date specified, unless it’s used in a Preset or an RSS Feed.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "name": "filter name"
  }
}

Example

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// creating Filters for Timezones
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}

listFilters

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

Returns a list of available segments (filters) with their conditions.

Request Body

Name	Required	Type	Description
auth*	Yes	string	API access token from Pushwoosh Control Panel.
application*	Yes	string	Pushwoosh application code.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

Example

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}

deleteFilter

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

Deletes an existing filter.

Request Body

Name	Type	Description
auth*	string	API access token from Pushwoosh Control Panel.
name*	string	Filter name.

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // API access token from Pushwoosh Control Panel
    "name": "filter name"
  }
}

exportSegment

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

A scheduled request. Exports the list of subscribers that fall under specified Filter conditions.

Request body

Name	Required	Type	Description
auth*	Yes	string	API access token from Pushwoosh Control Panel.
filterExpression*	Yes	string	Filter conditions
exportData	No	array	Data to export. Possible values: `"hwids"`, `"push_tokens"`, `"users"`, `"tags"`, `"location"`. Including `"location"` adds `Latitude` and `Longitude` columns to the exported CSV. If `exportData` is omitted, `Latitude` and `Longitude` are included in the export by default.
filterCode	No	string	Pre-made filter code, can be used instead of filterExpression. Can be obtained from /listFilters API or address bar of your browser when viewing the filter in Control Panel.
applicationCode	Required if you’re using either `filterExpression` or `filterCode`.	string	Pushwoosh app code.
generateExport	No	boolean	By default set to `true`, and a response contains a link to download the file. If false, only devices count will be sent in response.
format	No	string	Sets the format of the exported file: “csv” or “json_each_line”. If omitted, the CSV file is generated.
tagsList	No	array	Specifies tags to export. To obtain the specific tags only, the “exportData” array should contain the “tags” value.
includeWithoutTokens	No	boolean	Set to `true` to include users without push tokens in the exported file. Default is `false`.

200 Successful

{
  "task_id": "177458"
}

{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // required. API access token from Pushwoosh Control Panel
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // filter conditions, refer to the Segmentation Language guide for syntax
  "filterCode": "12345-67890",                              // pre-made filter code, can be used instead of filterExpression
  "applicationCode": "00000-AAAAA",                         // Required if you're using either `filterExpression` or `filterCode`. Pushwoosh app code. Can be obtained from /listFilters API request or address bar of your browser while viewing the filter in Control Panel.
  "generateExport": true,                                   // if false, devices count only will be sent in response; by default, a response contains a link to download the CSV file
  "format": "json_each_line",                               // format of the file to present the data in: "csv" – the .csv file is downloaded; "json" – a JSON file with all expored devices; or "json_each_line" – JSON line for each device. If not specified, CSV is the default format.
  "exportData": ["hwids", "tags"],                          // optional. Data to export. Possible values: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys"
  "tagsList": ["Name", "Level"],                            // optional. Specifies tags to export. To obtain the specific tags only, the "tags" value should be sent within the "exportData" array or the "exportData" be empty.
  "includeWithoutTokens": true                              // optional. Set to true to include users without push tokens in the exported file. Default is false.
}

For example, to export all subscribers of a particular app, use the following Filter conditions:

{
  "auth": "yxoPUlwqm…………pIyEX4H",            // API access token from Pushwoosh Control Panel
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // Filter expression referencing app segment
  "applicationCode": "AAAAA-BBBBB"           // Required Pushwoosh app code
}

exportSegment results

POST https://api.pushwoosh.com/api/v2/audience/exportSegment/result

Retrieves the link to the CSV with the the /exportSegment results.

Request Body

Name	Type	Description
auth*	String	API access token from Pushwoosh Control Panel.
task_id*	String	Identificator received in your /exportSegment response.

200: OK

{
  "devicesCount": "24735",
  "csvFilename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}

Pass the “task_id” received in your /exportSegment response in the /exportSegment/result request body.

In the /exportSegment/result response, you’ll receive the “filename” parameter. Follow the link provided in that parameter value to automatically download a ZIP archive. Unpack the archive to retrieve the CSV or JSON file (depending on the “format” specified in your request) containing the devices’ data.

Starting April 3, 2025, authorization is required to download the file:

If downloading via a browser, simply log in to the Pushwoosh Control Panel to gain access.
If downloading via server software, include the following header in your request: Authorization: Token YOUR_API_TOKEN

If you specify the “exportData” in your /exportSegment request, the file downloaded will contain the data requested only. By default, the file contains the following user data:

Field	Description	Example of value
Hwid	Hardware ID of a device	01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8
User ID	User ID associating a device with a particular user. If no User ID assigned, the HWID is used.	user8192
Push Token	Unique identifier assigned to a device by cloud messaging gateways.	eeeb2fd7…0fc3547
Type	Platform type (integer).	1
Type (humanized)	Platform type (string).	iOS
Age	Value of the default Age tag.	29
ApplicationVersion	Value of the default Application Version tag.	1.12.0.0
City	Value of the default City tag.	us, boston
TagName	Value of a tag created in your account.	TagValue