Filtro

Tutti gli endpoint di elenco (ad esempio Elencare le campagne o Elencare i numeri di una lista nera) accettano un parametro di query filter opzionale, che restringe i record restituiti.

Sintassi

Il parametro filter è un oggetto JSON, inviato con codifica URL nella query string. Ogni chiave è il nome di un campo, e ogni valore è il valore con cui confrontarlo:

Quando l'oggetto contiene più di una chiave, tutte le condizioni devono essere soddisfatte (sono combinate con AND). Il filtro può contenere fino a 2048 caratteri.

I campi utilizzabili sono elencati nella sezione Campi di filtro di ogni endpoint di elenco. L'utilizzo di un campo non supportato dall'endpoint restituisce un errore 400 Bad Request, che include l'elenco dei campi validi.

Operatori

Per impostazione predefinita, una chiave confronta il campo per uguaglianza. Per utilizzare un confronto diverso, aggiungi uno dei seguenti suffissi al nome del campo:

Suffisso	Significato	Esempio
(nessuno)	Uguale a (vedi le regole di corrispondenza più avanti)	{"state":"Active"}
_gt	Maggiore di	{"attempts_gt":1}
_gte	Maggiore o uguale a	{"startDate_gte":"2026-09-01"}
_lt	Minore di	{"attempts_lt":3}
_lte	Minore o uguale a	{"endedAt_lte":"2026-09-30T23:59:59"}
_ovl	Il campo array contiene almeno uno dei valori	{"tagIds_ovl":["TAG_ID_1","TAG_ID_2"]}
_ctn	Il campo array contiene il valore	{"callflowIds_ctn":"CALLFLOW_ID"}

Gli operatori possono essere combinati sullo stesso campo per definire un intervallo:

Regole di corrispondenza

Il modo in cui viene confrontato un valore dipende dal tipo del campo:

• Campi di testo (ad esempio name o number): corrispondenza parziale, senza distinzione tra maiuscole e minuscole. {"name":"sales"} corrisponde a una campagna denominata "Q3 Sales Follow-up". È questo che rende possibili le ricerche parziali di numeri come {"number":"555"}.
• Campi identificatore (ids e i campi che terminano con Id, come phoneSystemId): corrispondenza esatta.
• Campi enum (ad esempio state o status): corrispondenza esatta, con distinzione tra maiuscole e minuscole, con uno dei valori documentati.
• Campi numerici (ad esempio attempts): confronto numerico, di solito combinato con un operatore.
• Campi booleani (ad esempio isArchived): true o false.
• Campi data e timestamp: stringhe ISO 8601, come "2026-09-01" o "2026-09-01T08:30:00". Gli scostamenti di fuso orario vengono ignorati.

Corrispondenza con uno qualsiasi di più valori

Quando il valore è un array e non viene utilizzato alcun suffisso di operatore, il campo deve corrispondere a uno qualsiasi dei valori dell'array:

Il campo speciale ids funziona allo stesso modo, ed è il modo più semplice per ottenere più record per ID in un'unica richiesta:

Un array vuoto non filtra nulla.

Oggetti annidati

Alcuni campi sono oggetti. Per filtrare in base a una proprietà dell'oggetto, invia un oggetto annidato con le proprietà che vuoi far corrispondere. Le proprietà annidate vengono confrontate in modo esatto:

I suffissi di operatore possono essere utilizzati solo sui campi di primo livello, non all'interno degli oggetti annidati.

Filtri predefiniti

Alcuni endpoint applicano un filtro predefinito quando viene inviato il parametro filter. Ad esempio, quando invii un filter a Elencare le campagne, anche vuoto ({}), le campagne archiviate vengono escluse, a meno che il filtro includa il campo isArchived. Quando il parametro filter viene omesso, non viene applicato alcun filtro predefinito, e le campagne archiviate sono incluse. I filtri predefiniti sono descritti nella pagina di ogni endpoint.

Codifica

Ricorda di applicare la codifica URL al valore di filter. Con cURL, il modo più semplice è combinare -G con --data-urlencode, come mostrato negli esempi. Gli esempi di codice per gli altri linguaggi utilizzano le funzioni standard di codifica URL di ciascun linguaggio.