API de Contactos: crear, listar, actualizar y buscar
Cómo gestionar contactos de Omnifox por API REST: crear, buscar, actualizar y combinar duplicados.
Mira este paso en el video · Contactos por API
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 portag,email,phone,countryy campos personalizados víafilter[cf.<clave>].GET /api/v1/contacts/search— búsqueda de texto libre.POST /api/v1/contacts— crea un contacto (first_namees 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
- Usa
upserten integraciones que reciben datos de formularios externos: evita duplicados por email o teléfono. - El parámetro
include=custom_fields,channel_identitiestrae relaciones sin llamadas adicionales. - Antes de fusionar contactos con
merge, revisa 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; confirma el
workspace_id. - 422 en creación: falta
first_nameo elemail/phonetiene formato inválido. - Contacto no aparece en la búsqueda: los filtros
filter[cf.*]solo aplican a campos personalizados conentity_type=contact; verifica el nombre interno (key) del campo en Configuración.
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.