Leads del CRM

Con /external/v1/leads tu aplicación lee y trabaja los leads del CRM de UTILIA OS de forma controlada y auditada. Sirve a herramientas de prospección (Apollo, Cognism, Lusha), a plataformas que sincronizan con otro CRM (HubSpot, Pipedrive, Salesforce) y a herramientas de soporte que necesitan ver la captación.

Autenticación

Todas las peticiones llevan la clave de API de la aplicación:

X-Api-Key: <api_key_de_la_app>

La clave se obtiene al dar de alta la aplicación en Ajustes › Creadas por tu empresa, necesitas entrar con tu cuenta y puedes rotarla desde su ficha sin reescribir tu aplicación.

Permisos de la API (scopes)

Sin el permiso necesario, la respuesta es 403 con errorCode: INSUFFICIENT_SCOPE.

crm:leads:convert y crm:leads:read:notes son permisos críticos: concederlos a una aplicación exige el rol de Super Administrador y un motivo de al menos 20 caracteres. Además, cada llamada a /convert exige su propio reason con esa misma longitud mínima.

Endpoints

La clave de API trabaja a nivel de organización: lee y cambia cualquier lead de tu organización, sin el alcance de filas que tenga en el CRM la persona responsable de la aplicación. Lo que la API crea (leads, contactos, clientes, oportunidades) queda a nombre de esa persona responsable; sin una responsable activa, la respuesta es 403 APP_RESPONSIBLE_INACTIVE.

Forma de las respuestas:

• Listados: { data, pagination: { page, limit, total, totalPages, hasNextPage, hasPreviousPage } }.
• Alta: { lead, recordedAt }, con 201.
• Cambios (actualización, puntuación, cualificar, descartar): { lead, changed, recordedAt }.
• Conversión: { lead, contactId, opportunityId, clientId, changed, recordedAt }.
• Sincronización: { data, nextCursor, hasMore }.

Un lead tiene esta forma (score y temperature solo con ?include=scoring y crm:leads:read:scoring; notes, con ?include=notes y crm:leads:read:notes):

{
  "id": "ld-42",
  "organizationId": "org-1",
  "firstName": "Luis",
  "lastName": "Santana",
  "fullName": "Luis Santana",
  "companyName": "Talleres Santana",
  "email": "luis@talleres.example",
  "phone": "+34 928 000 002",
  "position": "Gerente",
  "source": "Apollo",
  "status": "NEW",
  "stage": "INITIAL_CONTACT",
  "priority": "MEDIUM",
  "isConverted": false,
  "convertedToContactId": null,
  "createdAt": "2026-10-19T08:00:00.000Z",
  "updatedAt": "2026-10-19T08:00:00.000Z",
  "lastContactedAt": null,
  "convertedAt": null
}

Crear un lead

Listar y buscar

Consultar un lead

Sincronizar por cambios

Funciona igual que la de clientes: lo explica Sincronizar por cambios.

Actualizar un lead

Admite los mismos campos que el alta, todos opcionales, y expectedUpdatedAt. Un campo que omites no se toca.

Qué puede cambiar tu aplicación

Desde la API, un lead se cualifica, se descarta o se convierte. Los estados Contactado y Negociando los pone tu equipo desde el CRM.

Cuerpo de las acciones

• qualify: reason (hasta 500 caracteres) y source, que admite external_app, crm_sync, manual o automation.
• disqualify: reason (hasta 500 caracteres) y source, con los mismos valores más bounce.
• convert: reason (de 20 a 1.000 caracteres), createOpportunity (opcional, false por defecto) y targetClientId (opcional): la ficha de cliente existente a la que vincular el contacto (si no existe, 404 CLIENT_NOT_FOUND). Sin targetClientId, se crea un cliente nuevo con los datos del lead. Con createOpportunity: true, el plan tiene que incluir las oportunidades (crm.opportunities); si no, 403 CAPABILITY_NOT_ENABLED y no se convierte nada.

Los campos personalizados del CRM no salen por esta API. Puedes leerlos y escribirlos por MCP: lo explica el apartado «Campos personalizados del CRM» de la referencia MCP.

Ejemplos

# Listar leads activos
curl -H "X-Api-Key: $KEY" \
  "https://os.utilia.ai/api/external/v1/leads?limit=25"
 
# Cualificar un lead
curl -X POST \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"reason":"Pidió una demostración y encaja en el perfil","source":"external_app"}' \
  "https://os.utilia.ai/api/external/v1/leads/ld-42/qualify"
 
# Convertir (no se puede deshacer)
curl -X POST \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"reason":"Aceptó la propuesta económica y empezamos la implantación","createOpportunity":true}' \
  "https://os.utilia.ai/api/external/v1/leads/ld-42/convert"

// SDK JavaScript
import { UtiliaSDK } from '@utilia-os/sdk-js';
 
const sdk = new UtiliaSDK({ baseURL: 'https://os.utilia.ai/api', apiKey: KEY });
 
const page = await sdk.externalLeads.list({ limit: 25 });
 
await sdk.externalLeads.qualify('ld-42', {
  reason: 'Pidió una demostración y encaja en el perfil',
  source: 'external_app',
});
 
const conv = await sdk.externalLeads.convert('ld-42', {
  reason: 'Aceptó la propuesta económica y empezamos la implantación',
  createOpportunity: true,
});

# SDK Python
from utilia_sdk import (
    ConvertLeadInput,
    ExternalLeadListFilters,
    QualifyLeadInput,
    UtiliaSDK,
)
 
async with UtiliaSDK(base_url="https://os.utilia.ai/api", api_key=KEY) as sdk:
    page = await sdk.external_leads.list(ExternalLeadListFilters(limit=25))
 
    await sdk.external_leads.qualify(
        "ld-42",
        QualifyLeadInput(
            reason="Pidió una demostración y encaja en el perfil",
            source="external_app",
        ),
    )
 
    conv = await sdk.external_leads.convert(
        "ld-42",
        ConvertLeadInput(
            reason="Aceptó la propuesta económica y empezamos la implantación",
            create_opportunity=True,
        ),
    )

Avisos a tu servidor de lead

Seis eventos a los que puedes suscribir la aplicación desde su ficha. Si el cambio lo hizo tu propia aplicación, no le llega el aviso; al resto de aplicaciones suscritas, sí.

Errores propios de estos endpoints

Límites de uso

Al superar un límite, la API responde 429 con la cabecera Retry-After, que indica los segundos que faltan para que se renueve.

Con los SDK oficiales

• JavaScript (@utilia-os/sdk-js): sdk.externalLeads con once métodos: list, get, search, byEmail, sync, qualify, disqualify, convert, create, update y updateScore.
• Python (utilia-sdk): sdk.external_leads con los mismos once métodos, en versión asíncrona y síncrona.

Las versiones de los dos SDK están en un único sitio: Versiones y compatibilidad. Consúltalo antes de fijar la dependencia de tu proyecto.

Decisiones de producto

• No hay DELETE sobre leads desde fuera: la única baja es /disqualify, que pasa el lead a LOST.
• /convert no se puede deshacer: crea un contacto y, si lo pides, una oportunidad.
• Las notas internas del lead solo salen con su permiso propio (crm:leads:read:notes).

Cada cambio queda en el registro de auditoría con la dirección IP y el cliente que lo hizo, y cada organización solo ve sus propios leads.

Siguiente paso

Tras integrar la lectura, suscribe la aplicación a los eventos LEAD_* desde su ficha para mantener la captación sincronizada sin consultar la API cada poco. Para trabajar también con la ficha de cliente vinculada, consulta Clientes del CRM; el catálogo completo de eventos está en Contenido de los avisos.