# API de segmentation (Filtres)

## createFilter

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

Crée un nouveau filtre.

**Corps de la requête**

| Nom | Requis | Type | Description |
| --- | --- | --- | --- |
| auth\* | Oui | string | [Jeton d'accès API](/fr/developer/api-reference/api-identifiers/#api-access-token) depuis le Control Panel de Pushwoosh. |
| name\* | Oui | string | [Nom du filtre](/fr/developer/api-reference/api-identifiers/#segment--filter-name). |
| filter\_expression\* | Oui | string | <p>Expression construite selon les règles du <a href="/developer/api-reference/segmentation-filters-api/segmentation-language/">langage de segmentation</a>. <br /><strong>Exemple :</strong> <code>T("City", eq, "Madrid")</code> pour segmenter les utilisateurs dont la ville est Madrid.</p> |
| application | Non | string | [Code d'application Pushwoosh](/fr/developer/api-reference/api-identifiers/#application-code). Ce paramètre n'est utilisable qu'avec la configuration haute vitesse ; omettez-le sinon. |
| expiration\_date | Non | string | Expiration du filtre. Le filtre sera automatiquement supprimé à une date spécifiée, sauf s'il est utilisé dans un préréglage ou un flux RSS. |

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



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

Retourne une liste des segments (filtres) disponibles avec leurs conditions.

**Corps de la requête**

| Nom | Requis | Type | Description |
| --- | --- | --- | --- |
| auth\* | Oui | string | [Jeton d'accès API](/fr/developer/api-reference/api-identifiers/#api-access-token) depuis le Control Panel de Pushwoosh. |
| application\* | Oui | string | [Code d'application Pushwoosh](/fr/developer/api-reference/api-identifiers/#application-code) |


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

```


**Exemple**
```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}
```

## deleteFilter

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

Supprime un filtre existant.

**Corps de la requête**

| Nom | Type | Description |
| --- | --- | --- |
| auth\* | string | [Jeton d'accès API](/fr/developer/api-reference/api-identifiers/#api-access-token) depuis le Control Panel de Pushwoosh. |
| name\* | string | [Nom du filtre](/fr/developer/api-reference/api-identifiers/#segment--filter-name). |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>



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

## exportSegment

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

Une requête planifiée. Exporte la liste des abonnés qui correspondent aux conditions de filtre spécifiées.

**Corps de la requête**
| Nom <div style="width:100px"></div> | Requis <div style="width:100px"></div> | Type | Description |
| --- | --- | --- | --- |
| auth\* | Oui | string | [Jeton d'accès API](/fr/developer/api-reference/api-identifiers/#api-access-token) depuis le Control Panel de Pushwoosh. |
| filterExpression\* | Oui | string | Conditions du filtre |
| exportData | Non | array | Données à exporter. Valeurs possibles : `"hwids"`, `"push_tokens"`, `"users"`, `"tags"`, `"location"`. L'inclusion de `"location"` ajoute les colonnes `Latitude` et `Longitude` au CSV exporté. Si `exportData` est omis, `Latitude` et `Longitude` sont incluses dans l'exportation par défaut. |
| filterCode | Non | string | [Code de filtre](/fr/developer/api-reference/api-identifiers/#segment--filter-code) prédéfini, peut être utilisé à la place de `filterExpression`. Peut être obtenu depuis l'API `/listFilters` ou la barre d'adresse de votre navigateur lors de la visualisation du filtre dans le Control Panel. |
| applicationCode | Requis si vous utilisez `filterExpression` ou `filterCode`. | string | [Code d'application Pushwoosh](/fr/developer/api-reference/api-identifiers/#application-code) |
| generateExport | Non | boolean | Par défaut, défini sur `true`, et une réponse contient un lien pour télécharger le fichier. Si `false`, seul le nombre d'appareils sera envoyé dans la réponse. |
| format | Non | string | Définit le format du fichier exporté : "csv" ou "json\_each\_line". Si omis, le fichier CSV est généré. |
| tagsList | Non | array | Spécifie les [tags](/fr/developer/api-reference/api-identifiers/#tag) à exporter. Pour n'obtenir que les tags spécifiques, le tableau "exportData" doit contenir la valeur "tags". |
| includeWithoutTokens | Non | boolean | Définir sur `true` pour inclure les utilisateurs sans jetons push dans le fichier exporté. La valeur par défaut est `false`. |


<Tabs>
<TabItem label="200 Réussi">
```json
{
  "task_id": "177458"
}
```
</TabItem>
</Tabs>



```json title="Exemple"
{
  "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.
}
```

<Aside type="note">
Veuillez trouver la référence du langage de segmentation pour écrire des expressions de filtre [ici](/fr/developer/api-reference/segmentation-filters-api/segmentation-language/).
</Aside>

Par exemple, pour exporter tous les abonnés d'une application particulière, utilisez les conditions de filtre suivantes :

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

<Aside type="caution">
Dans la réponse, vous obtiendrez le **`task_id`** pour obtenir le fichier résultant. Ensuite, appelez [/exportSegment/result](./#exportsegment-results) avec ce `task_id` dans le corps de la requête pour récupérer le fichier résultant.
</Aside>

## exportSegment résultats

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

**Récupère le lien vers le CSV avec les résultats de /exportSegment.**

**Corps de la requête**

| Nom | Type | Description |
| --- | --- | --- |
| auth\* | String | [Jeton d'accès API](/fr/developer/api-reference/api-identifiers/#api-access-token) depuis le Control Panel de Pushwoosh. |
| task\_id\* | String | Identifiant reçu dans votre réponse `/exportSegment`. |

<Tabs>
<TabItem label="200 : OK">
```json
{
  "devicesCount": "24735",
  "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}
```
</TabItem>
</Tabs>

Passez le "**task\_id**" reçu dans votre réponse `/exportSegment` dans le corps de la requête `/exportSegment/result`.

Dans la réponse `/exportSegment/result`, vous recevrez le paramètre "filename". Suivez le lien fourni dans la valeur de ce paramètre pour télécharger automatiquement une archive ZIP.
Décompressez l'archive pour récupérer le fichier CSV ou JSON (selon le "format" spécifié dans votre requête) contenant les données des appareils.

À partir du 3 avril 2025, une autorisation sera requise pour télécharger le fichier :

- Si vous téléchargez via un **navigateur**, connectez-vous simplement au **Control Panel de Pushwoosh** pour y accéder.
- Si vous téléchargez via un **logiciel serveur**, incluez l'en-tête suivant dans votre requête :
`Authorization: Token YOUR_API_TOKEN`

Si vous spécifiez "exportData" dans votre requête `/exportSegment`, le fichier téléchargé ne contiendra que les données demandées. Par défaut, le fichier contient les données utilisateur suivantes :

| **Champ** | Description | Exemple de valeur |
| --- | --- | --- |
| Hwid | [ID matériel d'un appareil (HWID)](/fr/developer/api-reference/api-identifiers/#hardware-id) | 01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8 |
| User ID | [ID utilisateur](/fr/developer/api-reference/api-identifiers/#user-id) associant un appareil à un utilisateur particulier. Si aucun ID utilisateur n'est attribué, le HWID est utilisé. | user8192 |
| Push Token | Identifiant unique attribué à un appareil par les passerelles de messagerie cloud. [En savoir plus](/fr/developer/api-reference/api-identifiers/#push-token) | eeeb2fd7....0fc3547 |
| Type | Type de plateforme (entier). | 1 |
| Type (humanized) | Type de plateforme (chaîne de caractères). | iOS |
| Age | Valeur du tag par défaut Âge. | 29 |
| ApplicationVersion | Valeur du tag par défaut Version de l'application. | 1.12.0.0 |
| City | Valeur du tag par défaut Ville. | us, boston |
| TagName | Valeur d'un tag créé dans votre compte. | TagValue |