Crear contacto

POST/clients/{clientId}/contacts

Da de alta un contacto en el CRM de un cliente (por ejemplo, un lead que llega a n8n).

Crea el contacto igual que el botón «Nuevo contacto» del panel, con el origen «API» para que puedas filtrarlo en Contactos.

Hace falta al menos un nombre, un email o un teléfono. Si el email o el teléfono ya los tiene otro contacto de ese CRM, responde 409 con el id del contacto existente y no se cobra la llamada: puedes usarlo para actualizarlo con PATCH.

La etapa y los campos personalizados tienen que ser del CRM de ese cliente. Si algo no es válido, no se crea nada.

Autenticación

Cabecera Authorization: Bearer ack_live_…. Permiso necesario: contacts:write. Cada llamada correcta consume créditos (créditos y límites).

Parámetros de la ruta

clientIduuidobligatorio

Id del cliente.

Cuerpo (JSON)

namestring

Nombre (hasta 160 caracteres).

emailstring

Email. Se guarda en minúsculas.

phonestring

Teléfono. Se normaliza igual que en el panel (p. ej. «600 11 22 33» y «600112233» son el mismo).

companystring

Empresa.

notesstring

Notas (hasta 2.000 caracteres).

stageIduuid | null

Etapa del CRM del cliente (ver «Opciones del CRM»).

customFieldsobject

Campos personalizados: { idDelCampo: valor }. Un valor vacío o null borra el dato.

Respuestas

201Correcto. Consume créditos.

401UNAUTHORIZED · Falta el token o no es válido.

401TOKEN_REVOKED · El token se ha revocado.

401TOKEN_EXPIRED · El token ha caducado.

403PLAN_REQUIRED · La cuenta no tiene el plan Agentes ilimitados.

402NO_CREDITS · No quedan créditos en la cuenta.

429RATE_LIMITED · Más de 60 llamadas por minuto con el mismo token.

403FORBIDDEN_SCOPE · El token no tiene el permiso necesario.

404NOT_FOUND · El cliente no existe, no es tuyo o el token está limitado a otro cliente.

409CONTACT_EXISTS · Ya hay un contacto con ese email o teléfono (details.contactId).

422VALIDATION_ERROR · Falta nombre, email o teléfono, o algún dato no es válido.

Las respuestas de error no consumen créditos.

curl -X POST "https://agentclic.com/api/public/pro/v1/clients/3f1c2a8e-5b7d-4e19-9a62-0c4d8b7e1f20/contacts" \
  -H "Authorization: Bearer ack_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lucía Martín","email":"lucia@example.com","phone":"600 11 22 33","company":"Clínica Sol","notes":"Viene del formulario de la web","stageId":"b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601","customFields":{"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f":"Implantes"}}'

Cuerpo de ejemplo

{
  "name": "Lucía Martín",
  "email": "lucia@example.com",
  "phone": "600 11 22 33",
  "company": "Clínica Sol",
  "notes": "Viene del formulario de la web",
  "stageId": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601",
  "customFields": {
    "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f": "Implantes"
  }
}

Respuesta201

{
  "contact": {
    "id": "8a2e4c61-1d3b-4f7a-b9e0-5c6d7e8f9a01",
    "name": "Lucía Martín",
    "email": "lucia@example.com",
    "phone": "+34600112233",
    "company": "Clínica Sol",
    "notes": "Viene del formulario de la web",
    "source": "api",
    "channel": "api",
    "stageId": "b7c1d2e3-4f50-4a61-8b72-9c83d4e5f601",
    "tags": [],
    "conversationId": null,
    "lastContactAt": null,
    "createdAt": "2026-11-03T10:15:00.000Z",
    "updatedAt": "2026-11-03T10:15:00.000Z",
    "customFields": [
      {
        "fieldId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "value": "Implantes"
      }
    ],
    "origins": []
  }
}