API de leads

POST /api/v1/leads crea un lead en el CRM desde cualquier sistema tuyo: tu web, tu tienda en línea, un formulario de WordPress o un proceso automático. Es la vía más flexible, porque decides tú qué campos envías, y la adecuada cuando la petición sale de un servidor. Si quieres captar desde el navegador de tus visitantes sin programar, usa un formulario insertado.

Endpoint

Autenticación

Envía la clave en la cabecera X-API-Key:

X-API-Key: utl_tu_clave_de_api

Las claves se crean en Ajustes › Seguridad › Claves de acceso (API), necesitas entrar con tu cuenta. Para crearlas necesitas el permiso API_CREDENTIALS_MANAGE; sin él puedes ver las claves existentes y su uso, pero no crear ninguna.

Campos del cuerpo

Cada campo de texto tiene un máximo de caracteres; si lo superas, la respuesta es 400. Es la causa más habitual de un 400 cuando los datos parecen correctos.

Nombre del lead. Si no envías fullName, se construye uniendo firstName y lastName con lo que llegue; si envías fullName, manda ese. Sin ninguno de los tres, la respuesta es 400.

Tus datos en metadata. El objeto se mezcla en la raíz de la metadata del lead y se aplica el último, así que una clave tuya llamada tracking, apiKey o leadForm sustituiría los datos que guarda el servidor. Anida siempre lo tuyo bajo una clave propia: {"metadata": {"miIntegracion": {"formId": 42}}}.

Campañas de correo. Esta API acepta las etiquetas utm, pero no el identificador del destinatario de una campaña (_ur) que sí acepta el envío de un formulario. Un lead creado por aquí se atribuye a la campaña por sus etiquetas, nunca al envío concreto que abrió esa persona.

Lo que guarda el servidor

Con cada lead, el servidor añade a metadata un bloque tracking:

tracking.ipstringobligatorio

IP de origen de la petición. 'unknown' si no se puede saber.

tracking.userAgentstring | nullobligatorio

Cabecera user-agent de la petición.

tracking.refererstring | nullobligatorio

Cabecera referer.

tracking.pageUrlstring | nullobligatorio

El pageUrl que enviaste.

tracking.utmobjectobligatorio

Las cinco claves source, medium, campaign, term y content, siempre presentes; las que no envíes valen null.

tracking.clientTimestampstring | nullobligatorio

El clientTimestamp que enviaste.

tracking.serverTimestampstringobligatorio

Momento en que el servidor creó el lead, en ISO 8601.

Junto a tracking, la metadata incluye apiKey (identificador, nombre y prefijo de la clave usada) y, si la clave pertenece a un formulario de captación, leadForm (identificador y nombre). Todo se ve en la ficha del lead en el CRM.

Qué pasa con el lead creado

• Se asigna a quien creó la clave de API, que figura también como su creador. No hay reparto por reglas: todos los leads de una clave van a la misma persona. Desde ahí puedes reasignarlos en el CRM.
• Nace en estado NEW, etapa INITIAL_CONTACT y prioridad MEDIUM.
• Recibe una puntuación: 20 puntos de partida, más 10 por phone o mobile, 15 por companyName, 10 por position, 5 por website y 5 por source, hasta un máximo de 100.
• Toma la categoría de origen que se deduce de source.
• Avisa a las personas y departamentos configurados en la clave.
• Dispara el evento de lead creado, que pueden escuchar las automatizaciones y los avisos a tu servidor.
• Suma a las estadísticas del formulario si la clave pertenece a uno.

Límites de peticiones

El límite de una clave no se puede cambiar después, ni siquiera al regenerarla: si necesitas otro, crea una clave nueva. Y aunque tu clave admita muchas peticiones por hora, reparte los envíos masivos en el tiempo para no chocar con el tope por dirección IP.

Las respuestas procesadas llevan X-RateLimit-Limit (máximo por hora de la clave), X-RateLimit-Remaining (lo que queda) y X-RateLimit-Reset (cuándo se reinicia el contador, en segundos Unix).

Al superar el límite de la clave, la respuesta 429 no lleva esas cabeceras ni Retry-After. Lee el campo retryAfter del cuerpo: los segundos que faltan para que se reinicie el contador.

{
  "statusCode": 429,
  "message": "Límite de peticiones superado. Inténtalo de nuevo más tarde.",
  "retryAfter": 2841
}

Respuesta (201)

{
  "success": true,
  "lead": {
    "id": "clx1234567890",
    "email": "juan@empresa.com",
    "fullName": "Juan Pérez",
    "source": "landing-contacto",
    "leadType": "CONTACT_FORM",
    "status": "NEW",
    "createdAt": "2026-10-08T10:30:00.000Z"
  }
}

Errores

El 403 de plan no se arregla reintentando ni con permisos: hay que ampliar el plan. Se distingue de otros 403 por el errorCode, como se explica en Errores de plan. Los duplicados (409) puedes revisarlos y fusionarlos desde los leads del CRM.

Ejemplos

curl -X POST 'https://os.utilia.ai/api/v1/leads' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: utl_tu_clave_de_api' \
  -d '{
    "email": "juan@empresa.com",
    "fullName": "Juan Pérez",
    "source": "landing-contacto",
    "leadType": "CONTACT_FORM",
    "phone": "+34 912 345 678",
    "companyName": "Empresa SL",
    "position": "Director Comercial",
    "tags": ["web", "interesado"],
    "utm": {
      "source": "google",
      "medium": "cpc",
      "campaign": "captacion-2026"
    }
  }'

El ejemplo de WordPress se ejecuta en tu servidor después de que Contact Form 7 envíe su correo, así que la clave no llega nunca al navegador.

Siguiente paso

Cuando el lead esté en el CRM, el flujo sigue allí: califícalo, conviértelo en oportunidad y, al ganarla, en cliente. Lo tienes en Leads. Si además quieres consultar o actualizar leads desde tu aplicación, con scopes y avisos, usa los endpoints de leads de la API externa.