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. |
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 | Type | Description |
---|---|---|
auth* | string | API access token from Pushwoosh Control Panel. |
filterExpression* | string | Filter conditions |
exportData | array | Data to export. Possible values: “hwids”, “push_tokens”, “users”, “tags”. |
filterCode | string | Pre-made filter code, can be used instead of filterExpression. Can be obtained from /listFilters API or adress bar of your browser when viewing the filter in Control Panel. |
applicationCode | string | Pushwoosh app code. Required if filterCode is applied instead of filterExpression. |
generateExport | 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 | string | Sets the format of the exported file: “csv” or “json_each_line”. If omitted, the CSV file is generated. |
tagsList | array | Specifies tags to export. To obtain the specific tags only, the “exportData” array should contain the “tags” value. |
{ "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", // Pushwoosh app code (needed when filterCode is applied instead of filterExpression). 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", "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.}
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\")" // 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. |
{ "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 |