Skip to main content
POST
Buscar contactos
Busca contactos mediante filtros avanzados. La API limita automáticamente los resultados a los contactos disponibles para tu API key.
Consulta primero Obtener esquema de contactos. Usa fields[].id para construir filtros y criterios de orden.

Endpoint

Body

Cada elemento de sort contiene:

Cómo nombrar los campos

Obtén los identificadores con Obtener esquema de contactos:
  • Usa fields[].id para búsquedas de texto completo, existencia, rangos y ordenamiento: email, createdAt o <field-id>.
  • Agrega .keyword para coincidencias exactas sobre texto, listas o teléfonos: email.keyword, phoneNumbers.keyword o <field-id>.keyword.
  • No uses fields[].ui.label; es una etiqueta visible y puede cambiar.

Operadores de consulta

Consultas comunes

__contactSearch ignora mayúsculas y acentos. Separa el texto por espacios y exige que cada término aparezca en alguno de los campos de nombre, apellidos, email o teléfonos.
También acepta un arreglo:
Usa match con el id del campo:
Para buscar un fragmento del email, usa __contactSearch.
Para una coincidencia exacta usa el mismo formato almacenado:
Para buscar por los últimos dígitos:
Usa terms para filtrar por cualquiera de los valores permitidos de un campo:
Los campos createdAt y updatedAt usan milisegundos Unix:
Para campos de fecha configurables, usa valores ISO 8601 según su jsonSchema.
  • must: todas las consultas deben coincidir.
  • filter: todas deben coincidir; úsalo para filtros exactos.
  • should: una o más pueden coincidir. Controla el mínimo con minimum_should_match.
  • must_not: excluye coincidencias.

Solicitud completa

Este ejemplo busca una coincidencia exacta por correo:

Respuesta exitosa (200)

Incrementa page mientras hasMore sea true. Conserva el mismo esQuery, limit y sort durante todo el recorrido.

Errores frecuentes

Authorizations

x-ib-api-key
string
header
required

Body

application/json
esQuery
object
required

Consulta formada con los operadores documentados en la guía de búsqueda.

page
integer
default:0
Required range: x >= 0
limit
integer
default:50
Required range: 1 <= x <= 100
sort
object[]

Response

Página de resultados.

success
boolean
required
hits
object[]
required
total
integer
required
Required range: x >= 0
page
integer
required
Required range: x >= 0
limit
integer
required
Required range: 1 <= x <= 100
hasMore
boolean
required