Filtrage

Tous les points de terminaison de listage (par exemple Lister les campagnes ou Lister les numéros d’une liste noire) acceptent un paramètre de requête facultatif filter, qui restreint les enregistrements renvoyés.

Syntaxe

Le paramètre filter est un objet JSON, envoyé encodé en URL dans la chaîne de requête. Chaque clé est un nom de champ, et chaque valeur est la valeur à comparer :

filter={"state":"Active","dialer":{"mode":"Predictive"}}

Lorsque l’objet contient plus d’une clé, toutes les conditions doivent être remplies (elles sont combinées avec AND). Le filtre peut contenir jusqu’à 2048 caractères.

Les champs utilisables sont listés dans la section Champs de filtre de chaque point de terminaison de listage. L’utilisation d’un champ non pris en charge par le point de terminaison renvoie une erreur 400 Bad Request, qui inclut la liste des champs valides.

Opérateurs

Par défaut, une clé compare le champ par égalité. Pour utiliser une autre comparaison, ajoutez l’un des suffixes suivants au nom du champ :

Suffixe	Signification	Exemple
(aucun)	Égal à (voir les règles de correspondance ci-dessous)	{"state":"Active"}
_gt	Supérieur à	{"attempts_gt":1}
_gte	Supérieur ou égal à	{"startDate_gte":"2026-09-01"}
_lt	Inférieur à	{"attempts_lt":3}
_lte	Inférieur ou égal à	{"endedAt_lte":"2026-09-30T23:59:59"}
_ovl	Le champ de type tableau contient au moins une des valeurs	{"tagIds_ovl":["TAG_ID_1","TAG_ID_2"]}
_ctn	Le champ de type tableau contient la valeur	{"callflowIds_ctn":"CALLFLOW_ID"}

Les opérateurs peuvent être combinés sur un même champ pour définir une plage :

filter={"startedAt_gte":"2026-09-01","startedAt_lt":"2026-10-01"}

Règles de correspondance

La manière dont une valeur est comparée dépend du type du champ :

• Champs texte (par exemple name ou number) : correspondance partielle insensible à la casse. {"name":"sales"} correspond à une campagne nommée « Q3 Sales Follow-up ». C’est ce qui rend possibles les recherches partielles de numéros comme {"number":"555"}.
• Champs identifiants (ids et les champs se terminant par Id, comme phoneSystemId) : correspondance exacte.
• Champs énumérés (par exemple state ou status) : correspondance exacte, sensible à la casse, avec l’une des valeurs documentées.
• Champs numériques (par exemple attempts) : comparaison numérique, généralement combinée avec un opérateur.
• Champs booléens (par exemple isArchived) : true ou false.
• Champs de date et d’horodatage : chaînes ISO 8601, comme "2026-09-01" ou "2026-09-01T08:30:00". Les décalages de fuseau horaire sont ignorés.

Correspondance avec plusieurs valeurs

Lorsque la valeur est un tableau et qu’aucun suffixe d’opérateur n’est utilisé, le champ doit correspondre à l’une des valeurs du tableau :

filter={"status":["NotContacted","RetryPending"]}

Le champ spécial ids fonctionne de la même manière, et constitue le moyen le plus simple de récupérer plusieurs enregistrements par ID en une seule requête :

filter={"ids":["01a0dedd-b9a2-729d-8e0a-4e3ad9197aea","01a0dad2-c0a6-7205-8d4e-a2d5f4197825"]}

Un tableau vide ne filtre rien.

Objets imbriqués

Certains champs sont des objets. Pour filtrer sur une propriété de l’objet, envoyez un objet imbriqué avec les propriétés que vous souhaitez faire correspondre. Les propriétés imbriquées sont comparées de manière exacte :

filter={"dialer":{"mode":"Power"}}

Les suffixes d’opérateur ne peuvent être utilisés que sur les champs de premier niveau, pas à l’intérieur des objets imbriqués.

Filtres par défaut

Certains points de terminaison appliquent un filtre par défaut lorsque le paramètre filter est envoyé. Par exemple, lorsque vous envoyez un filter à Lister les campagnes, même vide ({}), les campagnes archivées sont exclues, sauf si le filtre inclut le champ isArchived. Lorsque le paramètre filter est omis, aucun filtre par défaut n’est appliqué, et les campagnes archivées sont incluses. Les filtres par défaut sont décrits sur la page de chaque point de terminaison.

Encodage

N’oubliez pas d’encoder en URL la valeur de filter. Avec cURL, le plus simple est de combiner -G avec --data-urlencode, comme indiqué dans les exemples. Les exemples de code des autres langages utilisent les fonctions standard d’encodage d’URL de chaque langage.