Filtro

Todos os endpoints de listagem (por exemplo Listar campanhas ou Listar números da lista negra) aceitam um parâmetro de query string filter opcional, que restringe os registros retornados.

Sintaxe

O parâmetro filter é um objeto JSON, enviado codificado para URL na query string. Cada chave é um nome de campo, e cada valor é o valor com o qual comparar:

Quando o objeto contém mais de uma chave, todas as condições devem ser atendidas (elas são combinadas com AND). O filtro pode conter até 2048 caracteres.

Os campos que podem ser usados estão listados na seção Campos de filtro de cada endpoint de listagem. Usar um campo que não é suportado pelo endpoint retorna um erro 400 Bad Request, que inclui a lista de campos válidos.

Operadores

Por padrão, uma chave compara o campo por igualdade. Para usar uma comparação diferente, acrescente um dos seguintes sufixos ao nome do campo:

Sufixo	Significado	Exemplo
(nenhum)	Igual a (consulte as regras de correspondência abaixo)	{"state":"Active"}
_gt	Maior que	{"attempts_gt":1}
_gte	Maior ou igual a	{"startDate_gte":"2026-09-01"}
_lt	Menor que	{"attempts_lt":3}
_lte	Menor ou igual a	{"endedAt_lte":"2026-09-30T23:59:59"}
_ovl	O campo de array contém pelo menos um dos valores	{"tagIds_ovl":["TAG_ID_1","TAG_ID_2"]}
_ctn	O campo de array contém o valor	{"callflowIds_ctn":"CALLFLOW_ID"}

Os operadores podem ser combinados no mesmo campo para definir um intervalo:

Regras de correspondência

A forma como um valor é comparado depende do tipo do campo:

• Campos de texto (por exemplo name ou number): correspondência parcial, sem diferenciar maiúsculas e minúsculas. {"name":"sales"} corresponde a uma campanha chamada "Q3 Sales Follow-up". É isso que torna possíveis as buscas parciais de números como {"number":"555"}.
• Campos de identificador (ids e os campos que terminam em Id, como phoneSystemId): correspondência exata.
• Campos enum (por exemplo state ou status): correspondência exata, diferenciando maiúsculas e minúsculas, com um dos valores documentados.
• Campos numéricos (por exemplo attempts): comparação numérica, normalmente combinada com um operador.
• Campos booleanos (por exemplo isArchived): true ou false.
• Campos de data e de timestamp: strings ISO 8601, como "2026-09-01" ou "2026-09-01T08:30:00". Os deslocamentos de fuso horário são ignorados.

Correspondência com qualquer um de vários valores

Quando o valor é um array e nenhum sufixo de operador é usado, o campo deve corresponder a qualquer um dos valores do array:

O campo especial ids funciona da mesma forma, e é a maneira mais fácil de obter vários registros por ID em uma única solicitação:

Um array vazio não filtra nada.

Objetos aninhados

Alguns campos são objetos. Para filtrar por uma propriedade do objeto, envie um objeto aninhado com as propriedades que deseja comparar. As propriedades aninhadas são comparadas de forma exata:

Os sufixos de operador só podem ser usados nos campos de nível superior, não dentro de objetos aninhados.

Filtros padrão

Alguns endpoints aplicam um filtro padrão quando o parâmetro filter é enviado. Por exemplo, quando você envia um filter para Listar campanhas, mesmo vazio ({}), as campanhas arquivadas são excluídas, a menos que o filtro inclua o campo isArchived. Quando o parâmetro filter é omitido, nenhum filtro padrão é aplicado, e as campanhas arquivadas são incluídas. Os filtros padrão estão descritos na página de cada endpoint.

Codificação

Lembre-se de codificar para URL o valor de filter. Com cURL, a forma mais fácil é combinar -G com --data-urlencode, como mostrado nos exemplos. Os exemplos de código para as demais linguagens usam as funções padrão de codificação de URL de cada linguagem.