Segmentation (Filters) API

API methods to manage Filters

createFilter

/createFilter

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

Creates a new filter.

Request Body

NameTypeDescription

auth*

string

API access token from Pushwoosh Control Panel.

name*

string

Filter name.

conditions*

array

Filter conditions. Conditions syntax is explained in /createMessage.

operator

string

Operator values: 'AND', 'OR'.

application

string

Pushwoosh application code. This parameter is usable only with High-Speed Setup; omit otherwise.

expiration_date

string

Filter expiry. The filter will be automatically deleted on a date specified, unless it's used in a Preset or an RSS Feed.

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

For Custom Plan subscriptions only. For more details, please contact our Sales team.

Example
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // required, API access token from Pushwoosh Control Panel
    "name": "filter name", // required
    "conditions": [["TagName1", "IN", ["value1", "value2"]], ["TagName2", "IN", ["value1", "value2"]]], // required, filter conditions
    "operator": "AND", // optional, operator values: 'AND', 'OR'
    "application": "AAAAA-00000", // optional, this parameter is usable only with High-Speed setup; omit otherwise
    "expiration_date": "2018-12-31" // optional, filter expiry. The filter will be automatically deleted on date specified, unless it's used in a Push Preset or an RSS feed
  }
}

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

listFilters

/listFilters

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

Returns a list of available filters with their conditions.

Request Body

NameTypeDescription

auth*

string

API access token from Pushwoosh Control Panel.

{
    "status_code": 200,
    "status_message": "OK",
    "response": {
    "filters": [
       {
           "name": "filter name",
           "conditions": "#TagName1(value1, value2) AND #TagName2(value1, value2)",
           "application" : "AAAAA-ZZZZZ", //only for app-specific filters
           "expiration_date": "YYYY-MM-DD", //"null" for filters without expiration date
           "application" : "AAAAA-ZZZZZ" // only for app-specific filters
       }
    ]
  }
}

For Custom Plan subscriptions only. For more details, please contact our Sales team.

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

deleteFilter

/deleteFilter

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

Deletes an existing filter.

Request Body

NameTypeDescription

auth*

string

API access token from Pushwoosh Control Panel.

name*

string

Filter name.

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

For Custom Plan subscriptions only. For more details, please contact our Sales team.

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

exportSegment

/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

NameTypeDescription

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"
}

For Custom Plan subscriptions only. For more details, please contact our Sales team.

Example
{
        "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. 
}

Please find Segmentation Language reference for writing filter expressions here.

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
}

In the response, you'll get the task_id to get the resulting file. Then, call /exportSegment/result with that task_id in the request body to retrieve the resulting file.

/exportSegment results

/exportSegment/result

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

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

Request Body

NameTypeDescription

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 /exportSegment/result response, you'll get the "filename" parameter; go to the link specified as that param value. A ZIP archive will be downloaded automatically. Unpack the archive to get the CSV or JSON (depending on what "format" you've sent in the request) file with the devices' data.

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

Last updated