API de Contactos: crear, listar, actualizar y buscar

Cómo gestionar contactos de Omnifox por API REST: crear, buscar, actualizar y combinar duplicados.

Jul 11, 2026

La API de Contactos te permite sincronizar tu base de clientes con sistemas externos (CRM, ERP, hojas de cálculo, automatizaciones) sin pasar por la interfaz de Omnifox. Todos los endpoints viven bajo /api/v1/contacts y requieren un token Bearer obtenido con POST /api/v1/auth/login.

Requisitos

Token Bearer válido (Sanctum) para el workspace donde vive el contacto.
Opcional: parámetro ?workspace_id= si tu token tiene acceso a varios workspaces.

Endpoints principales

GET /api/v1/contacts — lista paginada, con filtros por tag, email, phone, country y campos personalizados vía filter[cf.<clave>].
GET /api/v1/contacts/search — búsqueda de texto libre.
POST /api/v1/contacts — crea un contacto (first_name es el único campo obligatorio).
GET/PUT/DELETE /api/v1/contacts/{contact} — ver, actualizar o eliminar un contacto puntual.
POST /api/v1/contacts/upsert — crea o actualiza según coincidencia de email/teléfono/canal.
POST /api/v1/contacts/merge — fusiona contactos duplicados.
POST /api/v1/contacts/{contact}/tags — agrega etiquetas.

Campos al crear un contacto

{
  "first_name": "Maria",
  "last_name": "Garcia",
  "email": "[email protected]",
  "phone": "+593991234567",
  "country": "EC",
  "custom_fields": { "empresa": "Acme Corp" },
  "tags": ["VIP", "Prospecto"]
}

Ejemplo: buscar contactos con la etiqueta VIP

curl -X GET "https://app.omnifox.io/api/v1/contacts?tag=VIP&per_page=50" \
  -H "Authorization: Bearer TU_TOKEN"

La respuesta trae la lista en data, junto con meta (página actual, total) y links para navegar.

Consejos

Usá upsert en integraciones que reciben datos de formularios externos: evita duplicados por email o teléfono.
El parámetro include=custom_fields,channel_identities trae relaciones sin llamadas adicionales.
Antes de fusionar contactos con merge, revisá cuál queda como "principal": la fusión no se puede deshacer.

Solución de problemas

403 Forbidden: tu token no tiene acceso a ese workspace; confirmá el workspace_id.
422 en creación: falta first_name o el email/phone tiene formato inválido.
Contacto no aparece en la búsqueda: los filtros filter[cf.*] solo aplican a campos personalizados con entity_type=contact; verificá el nombre interno (key) del campo en Configuración.

¿Te fue útil?