Filtro

Todos los endpoints de listado (por ejemplo Listar campañas o Listar números de lista negra) aceptan un parámetro de consulta filter opcional, que acota los registros devueltos.

Sintaxis

El parámetro filter es un objeto JSON, enviado codificado como URL en el query string. Cada clave es un nombre de campo, y cada valor es el valor con el que se compara:

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

Cuando el objeto contiene más de una clave, se deben cumplir todas las condiciones (se combinan con AND). El filtro puede contener hasta 2048 caracteres.

Los campos que se pueden usar se enumeran en la sección Campos de filtro de cada endpoint de listado. Usar un campo que el endpoint no admite devuelve un error 400 Bad Request, que incluye la lista de campos válidos.

Operadores

De forma predeterminada, una clave compara el campo por igualdad. Para usar una comparación diferente, agrega uno de los siguientes sufijos al nombre del campo:

Sufijo	Significado	Ejemplo
(ninguno)	Igual a (consulta las reglas de coincidencia más abajo)	{"state":"Active"}
_gt	Mayor que	{"attempts_gt":1}
_gte	Mayor o igual que	{"startDate_gte":"2026-09-01"}
_lt	Menor que	{"attempts_lt":3}
_lte	Menor o igual que	{"endedAt_lte":"2026-09-30T23:59:59"}
_ovl	El campo array contiene al menos uno de los valores	{"tagIds_ovl":["TAG_ID_1","TAG_ID_2"]}
_ctn	El campo array contiene el valor	{"callflowIds_ctn":"CALLFLOW_ID"}

Los operadores se pueden combinar sobre el mismo campo para definir un rango:

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

Reglas de coincidencia

La forma en que se compara un valor depende del tipo del campo:

• Campos de texto (por ejemplo name o number): coincidencia parcial, sin distinguir mayúsculas de minúsculas. {"name":"sales"} coincide con una campaña llamada "Q3 Sales Follow-up". Esto es lo que hace posibles las búsquedas parciales de números como {"number":"555"}.
• Campos identificadores (ids y los campos terminados en Id, como phoneSystemId): coincidencia exacta.
• Campos enum (por ejemplo state o status): coincidencia exacta, distinguiendo mayúsculas de minúsculas, con uno de los valores documentados.
• Campos numéricos (por ejemplo attempts): comparación numérica, normalmente combinada con un operador.
• Campos booleanos (por ejemplo isArchived): true o false.
• Campos de fecha y de marca de tiempo: strings ISO 8601, como "2026-09-01" o "2026-09-01T08:30:00". Los desplazamientos de zona horaria se ignoran.

Coincidencia con cualquiera de varios valores

Cuando el valor es un array y no se usa ningún sufijo de operador, el campo debe coincidir con cualquiera de los valores del array:

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

El campo especial ids funciona de la misma manera, y es la forma más sencilla de obtener varios registros por ID en una sola solicitud:

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

Un array vacío no filtra nada.

Objetos anidados

Algunos campos son objetos. Para filtrar por una propiedad del objeto, envía un objeto anidado con las propiedades que quieres que coincidan. Las propiedades anidadas se comparan de forma exacta:

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

Los sufijos de operador solo se pueden usar en los campos de primer nivel, no dentro de objetos anidados.

Filtros predeterminados

Algunos endpoints aplican un filtro predeterminado cuando se envía el parámetro filter. Por ejemplo, cuando envías un filter a Listar campañas, aunque sea vacío ({}), las campañas archivadas se excluyen, a menos que el filtro incluya el campo isArchived. Cuando se omite el parámetro filter, no se aplica ningún filtro predeterminado, y se incluyen las campañas archivadas. Los filtros predeterminados se describen en la página de cada endpoint.

Codificación

Recuerda codificar como URL el valor de filter. Con cURL, la forma más sencilla es combinar -G con --data-urlencode, como se muestra en los ejemplos. Los ejemplos de código de los demás lenguajes usan las funciones estándar de codificación de URL de cada lenguaje.