Crear o encontrar un contacto

Crea un contacto para el negocio autenticado, o devuelve el existente cuando algún identificador que envías ya pertenece a un contacto. Todos los campos son opcionales; cualquier campo no reconocido se guarda en collected_data.

POST/contacts

Autenticación

Este endpoint se autentica con tu API key enviada en la cabecera X-API-Key (formato ek_live_...). Puedes gestionar tus API keys desde la sección Dev Tools del panel.

Cuerpo de la solicitud

ParámetroTipoObligatorioDescripción
first_nameStringOpcionalNombre del contacto.
last_nameStringOpcionalApellido del contacto.
phone_numberStringOpcionalTeléfono en formato E.164 sin '+' (solo dígitos, 6-15 caracteres).
emailStringOpcionalCorreo electrónico del contacto.
external_idStringOpcionalTu propio id para esta persona (por ejemplo el id de usuario o cliente en tu sistema). Se guarda en el contacto y es lo primero que se busca en llamadas posteriores.

Ejemplo de solicitud

bash
curl -X POST "https://api.eclecticlabs.com/api/external/v2/contacts" \
  -H "X-API-Key: ek_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "56912345678",
    "email": "john@doe.com",
    "external_id": "crm-10482",
    "rut": "12345678-9"
  }'

Ejemplo de respuesta

json
{
  "success": true,
  "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created": true,
  "matched_by": "",
  "filled": [],
  "conflicts": []
}

Campos de la respuesta

  • contact_idUUID del contacto creado o encontrado.
  • createdtrue cuando se creó un contacto nuevo (201), false cuando se devolvió uno existente (200).
  • matched_byCómo se encontró el contacto existente: external_id, phone o email. Vacío cuando se creó un contacto.
  • filledIdentificadores que le faltaban al contacto existente y se agregaron desde esta solicitud: email, phone, external_id.
  • conflictsOtros contactos a los que apuntan tus identificadores, cada uno con su contact_id y el identificador matched_by. Vacío cuando todo coincidió con el mismo contacto.

Notas

  • Antes de crear, el contacto se busca por external_id, luego por phone_number y luego por email (sin distinguir mayúsculas). Se devuelve la primera coincidencia con created: false, se completan los identificadores que le faltan y los campos adicionales se combinan con su collected_data.
  • Los teléfonos coinciden con o sin el 9 de los móviles (Chile, Argentina) y el 1 antiguo (México). Un número chileno enviado sin el 9 se guarda con él, para que los mensajes de WhatsApp de la persona caigan en el mismo contacto.
  • Cuando los identificadores pertenecen a contactos distintos no se combina nada: se devuelve la primera coincidencia y las demás se listan en conflicts. Decide tú y llama a POST /contacts/merge si son la misma persona.
  • Cualquier campo adicional se almacena en collected_data del contacto.
  • Posibles errores: 400 (validación), 401 (API key inválida o ausente), 500 (error interno).