Documentación de la API de Relevant

Esta guía es para la persona que va a conectar un sistema externo (portal, tienda, app, ERP) con Relevant. La API v1 tiene tres endpoints: uno para registrar leads, otro para avisar que pasó algo con un lead ya registrado (y, si cambió el precio, actualizar su monto) y otro para corregir los datos de un contacto. El orden natural de integración es el de este documento: obtener la llave, registrar un lead, enviar un evento y, cuando haga falta, corregir un contacto. Si buscas la explicación para quien administra la cuenta (qué es el origen, cómo armar la automatización que escucha el evento), está en Conecta tu sistema a Relevant.

Antes de empezar

Base URL: https://app.relevantleads.io
Formato: JSON en el cuerpo y en la respuesta. Envía Content-Type: application/json. El cuerpo debe ser un objeto JSON (un arreglo o un valor suelto se rechaza).
Autenticación: encabezado Authorization: Bearer <llave>.
Métodos: POST en leads y eventos, PATCH en contactos. No hay CORS: el navegador bloquea la llamada, así que llama desde tu servidor, no desde el navegador del usuario final.
Entorno: no existe sandbox ni llaves de prueba. Todas las llaves son rk_live_ y operan sobre la cuenta real. Para probar sin arriesgar datos, usa un embudo de pruebas y leads de prueba.

1. La llave

Una persona con rol Owner o Admin la crea en Ajustes, API, Nueva llave (grupo Admin Center). Al crearla define tres cosas que viven en la llave, no en cada envío:

El embudo y etapa destino por defecto de los leads que entren con ella (tu envío puede sobrescribirlos, ver abajo).
El origen con el que se etiquetan esos leads en Contactos, Atribución y reportes (por ejemplo “Registro web”; si no se configura, “Registro externo”).
Su nombre, que aparece en las notas de sistema del chat del lead: “Datos del registro (nombre)” en cada registro con custom_data que crea o reutiliza un lead, y “Evento recibido de (nombre)” en cada evento.

Formato: rk_live_ seguido de 43 caracteres, 51 en total. Se muestra completa una sola vez al crearla; Relevant solo guarda un hash. Guárdala en variables de entorno o en tu gestor de secretos. Si se pierde, el administrador la revoca y crea otra. Cada petición autenticada actualiza el Último uso de la llave (aunque después falle por validación), así que quien administra puede ver desde Relevant que tu integración ya está llamando. Una llave revocada responde 401 de inmediato.

Errores de autenticación

HTTP	`code`	`message`	Causa
401	`unauthorized`	`Falta el encabezado Authorization. Envía "Authorization: Bearer <tu llave>".`	No mandaste el encabezado o no usa el esquema Bearer.
401	`unauthorized`	`La llave no es válida. Verifica que la copiaste completa y que pertenece a esta cuenta.`	La llave no empieza con `rk_live_` o no existe.
401	`unauthorized`	`La llave fue revocada. Genera una nueva en Ajustes > API.`	La llave existió y fue revocada.

2. Registrar un lead

POST /api/v1/leads Crea el contacto y su lead en el embudo destino. Si la persona ya existe, la reutiliza (ver deduplicación). Es seguro reintentar el mismo envío.

curl -X POST https://app.relevantleads.io/api/v1/leads \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mariana López",
    "phone": "5512345678",
    "country_code": "52",
    "email": "mariana@ejemplo.com",
    "external_id": "usr_8841",
    "amount": 1500,
    "company": "Acme",
    "custom_data": { "plan": "Pro" },
    "utm_source": "google",
    "utm_campaign": "primavera"
  }'

Campos del cuerpo

Campo	Tipo	Requerido	Notas
`name`	string	sí	Nombre del lead. Máximo 200 caracteres; si lo excede, la petición se rechaza (no se recorta).
`phone`	string o número	sí	De 10 a 15 dígitos (se cuentan solo los dígitos): 10 con lada, o de 11 a 15 si ya incluye el código de país. Con 8 o 9 dígitos la petición se rechaza (`422`, `fields.phone`). Envía solo dígitos y, si acaso, el `+`. Ver normalización abajo.
`country_code`	string	no	Código de país, solo dígitos, sin `+`. Por defecto `"52"` (México). Solo se usa cuando `phone` viene con exactamente 10 dígitos. Máximo 4 caracteres.
`email`	string	no	Se valida el formato (`No parece un correo válido.`). Máximo 254 caracteres.
`external_id`	string	no, recomendado	El identificador de esa persona en tu sistema. Es la identidad estable para deduplicar y para enviar eventos después. Máximo 128 caracteres.
`funnel_id`	uuid	no	Sobrescribe el embudo por defecto de la llave. Al hacerlo, la etapa por defecto de la llave se descarta y el lead cae en la primera etapa del embudo indicado, salvo que también mandes `stage_id`.
`stage_id`	uuid	no	Sobrescribe la etapa. Si mandas solo `stage_id`, el embudo se deduce de la etapa. Si mandas ambos y la etapa no pertenece al embudo, `422`.
`amount`	número	no	Valor estimado del lead en MXN, mayor o igual a 0. Se acepta también como texto con comas (`"1,500"`). Se guarda al crear el lead; en un lead reutilizado no se actualiza. Para cambiarlo después (un descuento, el flete, la cotización final), manda `amount` en `POST /api/v1/events` (sección 3, “Monto del lead”).
`company`	string	no	Empresa de la persona. Máximo 200 caracteres (más largo se recorta); si no es texto, `422`. Se guarda en el campo Empresa del contacto, visible en el panel del lead. En un contacto que ya existía, lo reemplaza si lo mandas con valor.
`location`	string	no	Ciudad o ubicación. Máximo 200 caracteres. Mismas reglas que `company`; se guarda en Ubicación del contacto.
`website`	string	no	Sitio web. Máximo 500 caracteres. Mismas reglas; se guarda en el contacto, aunque hoy no se muestra en ninguna pantalla ni en la exportación.
`custom_data`	objeto	no	Datos extra del registro. No se guardan como campos: se escriben como una nota de sistema en el chat del lead cada vez que el registro tiene lead, nuevo o reutilizado (ver abajo). No lo uses para la empresa, la ciudad ni el sitio web: para eso están `company`, `location` y `website`, que sí se guardan como campos.
`utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `referrer_url`	string	no	Atribución. En un contacto que ya existía solo se rellenan los que estaban vacíos. Máximo 500 caracteres cada uno.

Los campos de texto opcionales (external_id, email, country_code, company, location, website, UTMs) que exceden su máximo se recortan en silencio, no se rechazan. Solo name rechaza por longitud. Envía valores dentro de los límites para que lo que guardes coincida con lo que mandaste.

Normalización del teléfono

Relevant quita espacios, guiones, paréntesis, puntos y el +, y aplica estas reglas:

10 dígitos: se antepone country_code (o 52). "5512345678" se guarda como 525512345678.
Empieza con 521 y tiene 13 dígitos: se quita el 1 (formato viejo de celulares mexicanos). "5215512345678" se guarda como 525512345678.
Empieza con 00: se quitan los dos ceros.
De 11 a 15 dígitos (por ejemplo 12 con lada): se guarda tal cual; se asume que ya trae código de país.
8 o 9 dígitos: no se guarda. La petición responde 422 con fields.phone explicando el formato (“Debe tener 10 dígitos con lada (por ejemplo “8112345678”) o incluir el código de país (por ejemplo “+528112345678”, máximo 15 dígitos).”).

El teléfono guardado se devuelve en phone. En un contacto que ya existía, el teléfono guardado no se reemplaza.

Destino del lead

Por defecto: el embudo y etapa de la llave. Si la llave tiene embudo pero no etapa, la primera etapa del embudo. Si la llave no tiene embudo y el cuerpo tampoco, se crea solo el contacto (deal_id: null).
funnel_id en el cuerpo: se valida que sea de tu cuenta (404 si no). La etapa por defecto de la llave se descarta.
stage_id en el cuerpo: se valida que sea de tu cuenta (404 si no). Si viene sin funnel_id, el embudo es el de esa etapa.

Respuesta

201 Created cuando se creó el contacto o el lead. 200 OK cuando ambos ya existían y se reutilizaron.

{
  "contact_id": "2f1800a8-1ef7-4ca1-96b4-4b74a5bedbae",
  "deal_id": "9237e11f-cae3-4e7e-b8cb-8d011baa92ea",
  "created_contact": true,
  "created_deal": true,
  "phone": "525512345678",
  "funnel_id": "bf6929af-2d63-4d18-973f-232549b4e35f",
  "stage_id": "41ace7c2-5064-498b-8280-d11007e8c040"
}

deal_id es null cuando no hubo embudo destino: se creó solo el contacto.
funnel_id y stage_id son el embudo y la etapa donde quedó el lead al terminar la petición (Relevant los relee después de crear o reutilizar el lead). Si una automatización con disparador “Nuevo lead en etapa” lo movió al crearse, aquí ves la etapa final, no la de entrada.
Guarda contact_id y deal_id junto a tu usuario: deal_id sirve para enviar eventos con precisión, y contact_id para corregir el contacto aunque no tenga tu external_id (sección 4).

Deduplicación (idempotencia de registros)

Si envías external_id y ya existe un contacto con ese valor en tu cuenta, se reutiliza.
Si no envías external_id, o no coincide con ningún contacto, se busca por los últimos 10 dígitos del teléfono dentro de tu cuenta. Si más de un contacto termina en esos dígitos, se reutiliza el más antiguo (el que tiene el historial).
En un contacto reutilizado se actualizan name y email si los mandas, y se rellenan los UTMs vacíos. Si el contacto no tenía external_id y ahora lo mandas, se le guarda; si ya tenía otro, conserva el que tenía (y un evento con el nuevo external_id no lo encontrará: usa deal_id o el teléfono).
Si el contacto ya tiene un lead abierto en el embudo destino, se reutiliza ese lead (created_deal: false); no se tocan su título, monto ni etapa. Un segundo registro de la misma persona no es una oportunidad nueva.
Si su lead anterior ya se cerró (ganado o perdido), se crea uno nuevo.

Reintentar el mismo envío no genera duplicados.

`custom_data`

Se escribe en el chat del lead como una nota de sistema con el formato Datos del registro (nombre de la llave): clave: valor · clave: valor, visible para el equipo. Reglas:

Se escribe cada vez que el registro tiene lead: cuando lo crea (created_deal: true) y también cuando reutiliza uno abierto (created_deal: false). Por eso un reintento con custom_data deja la nota otra vez (sección 7). Si no hay embudo destino (deal_id: null), custom_data se descarta sin error.
Máximo 20 claves (las primeras, en orden), 40 caracteres por clave, 120 por valor, 600 en total. Los valores vacíos o nulos se omiten. Un valor anidado se serializa como texto JSON y se recorta a 120.
Un arreglo en custom_data se rechaza con 422.

Qué pasa en Relevant al registrar

El contacto y el lead se crean con el origen de la llave. El lead nace con prioridad Media, estado abierto y título igual a name.
Sobre un lead nuevo corren las reglas de auto-asignación de la cuenta (reglas, responsable de etapa, responsable de embudo). Si asigna a alguien, esa persona recibe la notificación de lead asignado.
Automatizaciones al crear: un lead nuevo dispara, dentro de la misma petición, las automatizaciones cuyo disparador “Nuevo lead en etapa” vigile la etapa donde entra; por eso stage_id en la respuesta puede ser distinto del destino. Un lead reutilizado no dispara nada al registrarse de nuevo, porque no cambia de etapa. Para actuar cuando pase algo después en tu sistema, usa eventos.
No se envía ningún mensaje de WhatsApp al lead.

3. Avisar de un evento del lead

POST /api/v1/events Úsalo cuando en tu sistema pase algo con un lead ya registrado: un pago, una activación, una cancelación. Relevant registra el evento, lo deja como nota en el chat del lead, notifica a la persona responsable y ejecuta las automatizaciones que estén escuchando ese evento en ese embudo. Si con el evento cambió el precio, el mismo envío puede actualizar el monto del lead (amount).

curl -X POST https://app.relevantleads.io/api/v1/events \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "pago_recibido",
    "external_id": "usr_8841",
    "payload": { "plan": "Pro", "monto": 1500 },
    "amount": 1500,
    "idempotency_key": "pago-usr_8841-2026-09-12"
  }'

Campos del cuerpo

Campo	Tipo	Requerido	Notas
`event`	string	sí	Nombre del evento: minúsculas, dígitos, `_`, `-` o `.`; el primer carácter debe ser letra o dígito; máximo 64. Se convierte a minúsculas antes de validar (`"PAGO_RECIBIDO"` se acepta como `pago_recibido`). Debe coincidir exactamente con el nombre configurado en el disparador Evento externo de la automatización; ese nombre se ve y se copia desde el panel del disparador.
`deal_id`	uuid	uno de los tres	El `deal_id` que devolvió el registro. Es la forma más precisa. Si lo mandas, `external_id` y `phone` se ignoran.
`external_id`	string	uno de los tres	El identificador de tu sistema, el mismo que mandaste al registrar. Forma recomendada si no guardaste `deal_id`. Máximo 128.
`phone`	string o número	uno de los tres	Teléfono del lead, con la misma regla que en el registro: de 10 a 15 dígitos (con 8 o 9, `422`). Se usa si no mandas `deal_id` ni `external_id`, o si `external_id` no coincide con ningún contacto.
`funnel_id`	uuid	no	Limita el evento a los leads abiertos de ese embudo. Se valida contra tu cuenta (`404` si no existe).
`payload`	objeto	no	Datos del evento: un objeto plano de hasta 20 claves, cada clave de 1 a 40 caracteres, valores de texto (hasta 500 caracteres), número, booleano o `null`, y 4 KB en total. Se muestran en el chat del lead y en la notificación (las claves que empiezan con `_` se ocultan del resumen), se guardan íntegros en el registro del evento y llegan a las acciones de la automatización: una acción Enviar plantilla puede usar cualquier clave como variable del mensaje (ver abajo). Si el payload rebasa un límite, la petición responde `422` con el motivo en `fields.payload`.
`amount`	número	no	Monto nuevo del lead en MXN, con las mismas reglas que en el registro: mayor o igual a 0, también como texto con comas. Reemplaza el monto del lead abierto que alcanza el evento, aunque alguien lo haya editado a mano. Con `null` o vacío no se toca. Ver “Monto del lead” abajo.
`idempotency_key`	string	no, recomendado	Clave única por evento (máximo 128). Un reintento con la misma clave devuelve el resultado original y no vuelve a ejecutar nada.

Cómo se resuelve el evento

Relevant localiza al lead: por deal_id si viene; si no, por external_id; si no coincide, por los últimos 10 dígitos de phone.
Toma sus leads abiertos (todos, o solo los del funnel_id indicado). Los leads cerrados no se tocan.
Si mandaste amount, lo escribe en el lead abierto antes de ejecutar nada (ver “Monto del lead” abajo).
Para cada lead abierto, ejecuta cada automatización activa que tenga un disparador Evento externo con ese nombre exacto y con el embudo del lead. En el editor, cada disparador de este tipo está ligado a un embudo; si la persona tiene leads abiertos en dos embudos y mandas el evento sin funnel_id, ambos leads reciben la nota y la notificación, pero solo se ejecuta la automatización del embudo que coincide.
Deja rastro: registro del evento, nota de sistema Evento recibido de <nombre de la llave>: <event> (<resumen del payload>) en el chat de cada lead abierto alcanzado (si el evento cambió el monto, la nota termina con · Monto: <anterior> → <nuevo>), y notificación dentro de la app a la persona asignada a cada uno.
Si la automatización tiene la acción Enviar plantilla, el lead recibe un Mensaje de WhatsApp aprobado en cuanto llega el evento, con sus variables tomadas del payload (por ejemplo {{2}} = clave monto), de los datos del contacto o del lead, o de texto fijo; si a una variable le falta el valor, no se envía y el chat lo dice. Cada mensaje entregado se cobra como difusión. Cómo se configura, en Automatizaciones.

Monto del lead (`amount`)

El monto se escribe antes de ejecutar las automatizaciones: si una de ellas marca el lead como ganado o manda una plantilla con Monto del lead, ya ve el nuevo.
Solo cambia leads abiertos. Si el evento no alcanza ninguno (outcome: "no_open_deals"), el monto se ignora.
El monto es de un lead. Si el contacto tiene varios leads abiertos y el evento los alcanza a todos, la respuesta es 422 validation_error con fields.amount (“El evento alcanza N leads abiertos de este contacto. Envía deal_id o funnel_id para indicar a cuál aplicar el monto.”) y no se registra ni se ejecuta nada: la idempotency_key queda libre. Reenvía con deal_id, o con funnel_id si el contacto tiene un solo lead abierto en ese embudo.
Si el monto cambió, la nota del evento en el chat lo dice al final: · Monto: $4,640 → $4,176.50 (si el lead no tenía monto, sin monto → $4,176.50). Si era el mismo, no se escribe nada.
Un reintento con la misma idempotency_key no vuelve a escribir el monto: devuelve el amount_update del envío original.
Si la respuesta es 500, el lead se queda con el monto que tenía antes del envío (salvo que alguien lo haya cambiado mientras tanto) y la clave queda libre: el reintento con la misma idempotency_key lo escribe.

Límites del `payload`

Relevant rechaza el evento completo (422 validation_error) cuando el payload:

tiene más de 20 claves (“Máximo 20 claves.”);
trae una clave vacía o de más de 40 caracteres (“Cada clave debe tener entre 1 y 40 caracteres.”);
trae un valor que es objeto o lista (“La clave “x” debe ser texto, número, booleano o null, no un objeto ni una lista.”);
trae un texto de más de 500 caracteres (“El valor de “x” supera 500 caracteres.”);
pesa más de 4 KB en total (“El payload completo supera 4096 bytes.”).

Manda solo lo que la automatización va a usar (un monto, un plan, un folio). Lo que necesites conservar completo guárdalo en tu sistema y manda la referencia.

Respuesta

200 OK siempre que el lead exista, aunque no tenga leads abiertos o ninguna automatización lo escuche.

{
  "event_id": "c0a1f3d2-8b4e-4d1a-9f0e-2a6b7c8d9e01",
  "event": "pago_recibido",
  "contact_id": "2f1800a8-1ef7-4ca1-96b4-4b74a5bedbae",
  "deal_ids": ["9237e11f-cae3-4e7e-b8cb-8d011baa92ea"],
  "deals": [{ "deal_id": "9237e11f-cae3-4e7e-b8cb-8d011baa92ea", "handovers_fired": 1 }],
  "handovers_fired": 1,
  "outcome": "fired",
  "amount_update": { "deal_id": "9237e11f-cae3-4e7e-b8cb-8d011baa92ea", "previous": 4640, "amount": 4176.5, "changed": true },
  "duplicate": false,
  "received_at": "2026-09-12T04:00:00.000Z"
}

amount_update es null cuando no mandaste amount o el evento no alcanzó ningún lead abierto. Si no, trae el lead (deal_id), el monto que tenía (previous, puede ser null), el que mandaste (amount) y si de verdad cambió (changed). changed: false significa que ya tenía ese monto o que el lead se cerró justo antes de escribirlo.

`outcome`	Significado
`fired`	Al menos una automatización se ejecutó. `handovers_fired` cuenta automatizaciones ejecutadas (no acciones), en total y por lead en `deals`.
`no_automation`	El lead tiene leads abiertos, pero ninguna automatización activa escucha ese evento en ese embudo. El evento quedó registrado y anotado en el chat.
`no_open_deals`	La persona existe pero no tiene leads abiertos (ya se ganó o se perdió, o no está en el embudo indicado). Con `deal_id` de un lead cerrado también se responde así, no `404`.
`pending`	Solo con `duplicate: true`: el envío original con esa `idempotency_key` todavía se está procesando (dos envíos simultáneos). Relevant esperó hasta 2 segundos; si necesitas el resultado final, reintenta con la misma clave.

Si el lead no existe: 404 not_found, con field igual a deal_id, external_id o phone según lo que mandaste. Regístralo primero con POST /api/v1/leads.

Idempotencia de eventos

La idempotency_key es única por cuenta y no caduca: la misma clave meses después sigue devolviendo el resultado original.
Un reintento con una clave ya recibida responde 200 con duplicate: true, el outcome y el amount_update originales, y sin el arreglo deals. No se ejecuta nada ni se vuelve a escribir el monto.
Si dos envíos con la misma clave llegan al mismo tiempo, solo uno ejecuta: la clave se reserva antes de ejecutar las automatizaciones. El otro recibe el resultado del primero con duplicate: true; si el primero sigue en proceso, Relevant espera hasta 2 segundos y, si aún no termina, responde con outcome: "pending".
En el caso raro de que ese resultado original no se pueda leer, el segundo envío recibe 409 conflict. Reintenta una vez: obtendrás el resultado original con duplicate: true.
Un 422 por amount o un 500 no gastan la clave: reenvía con la misma idempotency_key.

4. Corregir un contacto

PATCH /api/v1/contacts Úsalo cuando en tu sistema se corrija un dato de un contacto que ya registraste: el nombre, el teléfono, el correo, la empresa. Reenviar POST /api/v1/leads no sirve para eso: no cambia el teléfono, no borra datos y, si el lead ya se cerró, abre uno nuevo.

curl -X PATCH https://app.relevantleads.io/api/v1/contacts \
  -H "Authorization: Bearer rk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "usr_8841",
    "phone": "8112345678",
    "email": "mariana@restaurante.mx",
    "company": null
  }'

Cómo se identifica el contacto

Exactamente uno de estos dos:

Campo	Tipo	Notas
`external_id`	string	El mismo que mandaste al registrarlo. Máximo 128 caracteres.
`contact_id`	uuid	El `contact_id` que devolvió `POST /api/v1/leads`. Sirve cuando el contacto se registró sin `external_id` o con otro (ver deduplicación en la sección 2).

Si mandas los dos, o ninguno: 422 validation_error. Solo se buscan contactos de tu cuenta: si no existe, 404 not_found con field igual a external_id o contact_id.

Campos que se pueden cambiar

Un campo que no mandas no se toca. Un campo con null o "" se borra, salvo name y phone, que no se pueden borrar (mandarlos vacíos o con null da 422).

Campo	¿Se puede borrar?	Notas
`name`	No	De 1 a 200 caracteres.
`email`	Sí	Mismo formato que en el registro (`No parece un correo válido.`). Máximo 254 caracteres.
`phone`	No	String o número, con la misma regla que en el registro: 10 dígitos con lada (se completa con `country_code`) o de 11 a 15 si ya incluye el código de país. Solo dígitos y, si acaso, el `+`, espacios, guiones, paréntesis o puntos; con letras, `422`. Ver “Cambio de teléfono”.
`country_code`	No aplica	Código de país, solo dígitos, sin `+`. Solo junto con `phone`, y solo se usa cuando el teléfono trae 10 dígitos. Por defecto `"52"`. Sin `phone`, `422`.
`company`	Sí	Máximo 200 caracteres.
`location`	Sí	Máximo 200 caracteres.
`website`	Sí	Máximo 500 caracteres.

A diferencia del registro, un texto que pasa del máximo se rechaza con 422 en vez de recortarse: es una corrección y tiene que quedar exactamente lo que mandaste. Cualquier otro campo también da 422 con el detalle en fields: los del registro que aquí no van (funnel_id, stage_id, amount, custom_data, UTMs y referrer_url) y uno mal escrito. Para cambiar el monto del lead, usa amount en eventos (sección 3).

Cambio de teléfono

El mismo número en otro formato (+52 81 1234 5678, 5218112345678 o los 10 dígitos) no cuenta como cambio.
Si el número está bloqueado en tu cuenta: 422 blocked con field: "phone".
Si el número ya es de otro contacto de tu cuenta (se comparan los últimos 10 dígitos): 409 conflict con field: "phone" y conflict_contact_id. Los contactos nunca se fusionan: corrige el otro contacto o usa otro número.
El historial de WhatsApp se queda en el contacto. Si la persona vuelve a escribir desde el número viejo, entra como un contacto nuevo.
La ventana de 24 horas que contaba Relevant era del número viejo: Relevant la da por cerrada en los leads abiertos del contacto. Limitación conocida: en el chat la ventana todavía puede verse abierta por los mensajes del número viejo. Si un mensaje de texto libre al número nuevo falla, manda una plantilla aprobada.

Lo que no hace

No crea, mueve, cierra ni reabre leads, y no cambia su título, monto ni etapa. No asigna ni cambia el external_id del contacto: solo sirve para encontrarlo. No dispara automatizaciones, reglas de asignación ni notificaciones, no escribe en el chat y no manda WhatsApp.

Respuesta

200 OK, también cuando no cambió nada: repetir el mismo cuerpo devuelve changed: [].

{
  "contact_id": "2f1800a8-1ef7-4ca1-96b4-4b74a5bedbae",
  "external_id": "usr_8841",
  "changed": ["email", "phone", "company"],
  "contact": {
    "name": "Mariana López",
    "email": "mariana@restaurante.mx",
    "phone": "528112345678",
    "company": null,
    "location": "Monterrey",
    "website": null
  }
}

changed lista solo los campos que de verdad cambiaron. contact es cómo quedó el contacto; phone es el teléfono guardado (dígitos con lada, sin +).

5. Errores

Todas las respuestas de error tienen esta forma:

{
  "error": {
    "code": "validation_error",
    "message": "Hay campos inválidos. Revisa \"fields\".",
    "fields": { "phone": "Requerido. Teléfono con lada, por ejemplo \"5512345678\" o \"+525512345678\"." }
  }
}

HTTP	`code`	Cuándo	Qué hacer
401	`unauthorized`	Falta el encabezado, la llave no existe o fue revocada. El `message` distingue los tres casos.	Revisa la llave; si fue revocada, pide una nueva al administrador.
400	`invalid_json`	El cuerpo no es un objeto JSON válido (`El body debe ser un objeto JSON. Envía Content-Type: application/json.`).	Envía un objeto JSON.
413	`payload_too_large`	El cuerpo supera 16 KB (`El body supera el máximo de 16 KB.`).	Un lead cabe de sobra en 16 KB; revisa `custom_data` o `payload`.
422	`validation_error`	Algún campo no cumple el formato. `fields` trae el mensaje por campo. En leads, también cuando `stage_id` no pertenece al `funnel_id` indicado (`stage_id no pertenece al embudo indicado.`). En eventos, también cuando `amount` alcanza más de un lead abierto (ver “Monto del lead”). En contactos, también un texto más largo que su máximo, un campo que no se acepta, o mandar `external_id` y `contact_id` juntos o ninguno de los dos.	Corrige los campos indicados y reintenta.
422	`blocked`	El teléfono está bloqueado en tu cuenta (leads y contactos). Viene con `field: "phone"`.	Si de verdad quieres usarlo, desbloquéalo en Ajustes, WhatsApp, Bloqueados.
404	`not_found`	`funnel_id`, `stage_id` o `deal_id` no existen en tu cuenta, el lead del evento no existe (`external_id` o `phone`) o el contacto que quieres corregir no existe (`external_id` o `contact_id`). `field` indica cuál.	Usa identificadores de tu cuenta; para eventos, registra el lead primero.
409	`conflict`	En eventos, caso raro: dos envíos simultáneos con la misma `idempotency_key` y el resultado original no se pudo leer (lo normal es recibir ese resultado con `duplicate: true`, sin `409`). En contactos: el teléfono nuevo ya es de otro contacto (`field: "phone"` y `conflict_contact_id`).	En eventos, reintenta una vez: recibirás el resultado original con `duplicate: true`. En contactos, no reintentes: corrige el otro contacto o usa otro número.
500	`internal_error`	Fallo al guardar o al ejecutar. `step` indica el paso: en leads `contact_create_failed`, `deal_create_failed` o `unknown`; en eventos `fire` o `amount`; en contactos `contact_update_failed`.	Reintenta (en eventos, con la misma `idempotency_key`). Si persiste, escribe a soporte con el `step` y la hora.

Orden de evaluación en los tres endpoints: autenticación (401), cuerpo (413, 400), formato de los campos (422), existencia de identificadores (404), proceso (500). Después del 404 todavía pueden llegar estas respuestas: en leads, el 422 de stage_id que no pertenece al embudo y el 422 blocked; en eventos, el 422 por amount con varios leads abiertos; en contactos, el 422 blocked y el 409 conflict por el teléfono. Un evento con una idempotency_key ya recibida se contesta como duplicado justo después de revisar el formato, antes de validar funnel_id.

6. Límites y comportamiento

Tamaño del cuerpo: 16 KB.
Límite de tasa: no hay. La llave registra su último uso y puede revocarse al instante; ese es el mecanismo para detectar y cortar un abuso. Si vas a enviar volúmenes altos (miles por hora), avísanos antes a soporte@relevantleads.io.
Recortes silenciosos (leads y eventos): external_id e idempotency_key a 128, email a 254, UTMs a 500, country_code a 4 caracteres. En contactos no se recorta nada: un texto más largo que su máximo da 422.
Plan: el registro de leads, los eventos y la corrección de contactos funcionan en todos los planes. No hay validación de plan en estos endpoints.
Sin sandbox. Métodos: POST en leads y eventos, PATCH en contactos. No hay CORS: el navegador bloquea la llamada, así que llama desde tu servidor, no desde el navegador del usuario final.
Edición de llaves: quien administra la cuenta (Owner o Admin) puede editar una llave sin revocarla: nombre, embudo destino, etapa destino, origen y color. La llave sigue siendo la misma, así que tu sistema no cambia nada. Los leads que ya entraron con ella conservan su origen y lo muestran con el nombre y el color nuevos. La revocación no borra el historial de los leads que entraron con ella.

7. Tiempos de respuesta, timeouts y reintentos

Tiempos medidos el 31 de octubre de 2026, con la API en Oregón (EE. UU.), desde que el cliente envía la petición hasta que recibe la respuesta, una petición a la vez:

POST /api/v1/leads: ~0.9 s típico. La primera llamada en frío, después de un rato sin tráfico, puede tardar hasta ~2 s.
POST /api/v1/events: ~0.75 s típico.

Tu tiempo real depende de tu red y de dónde esté tu servidor. Timeout. Configura 15 s por petición: deja margen para una llamada en frío o un pico sin cortar envíos que sí iban a completarse. Reintento. Ante un timeout, un error de red o una respuesta 5xx, reintenta una vez con el mismo cuerpo:

En leads es seguro: el reintento no crea otro contacto ni otro lead (ver deduplicación en la sección 2). Si mandaste custom_data, su nota puede aparecer dos veces en el chat del lead.
En eventos, reintenta con la misma idempotency_key. Si el primer envío sí llegó, recibes su resultado con duplicate: true y las automatizaciones no se ejecutan otra vez. Sin idempotency_key, un reintento puede ejecutarlas dos veces.
En contactos es seguro: repetir el mismo cuerpo no cambia nada más (changed: []).

Un 4xx no se arregla reintentando el mismo cuerpo (salvo el 409 conflict de eventos, ver la sección 5): revisa code y message. Si el reintento también falla, no lo repitas en bucle: guárdalo y vuelve a intentarlo más tarde desde tu sistema. Conexión. Si mandas varias peticiones seguidas (por ejemplo, una carga de leads), reutiliza la conexión HTTP (keep-alive) en vez de abrir una nueva por petición: te ahorras establecer la conexión (TCP y TLS) en cada una. Los tiempos de arriba se midieron abriendo una conexión nueva por petición.

8. Buenas prácticas

Manda siempre external_id: hace seguros los reintentos y es lo que identifica al lead cuando envías eventos.
Guarda el deal_id que te devuelve el registro y úsalo en los eventos: es la forma más precisa, evita ambigüedades si la persona tiene varios leads y, si mandas amount, evita el 422 por varios leads abiertos.
Guarda también el contact_id: con él puedes corregir el contacto aunque no tenga tu external_id.
En eventos, manda siempre idempotency_key; construye la clave con algo que identifique la acción de negocio (por ejemplo pago-<id de tu pago>), no con la fecha y hora del envío.
Configura un timeout de 15 s y un solo reintento (sección 7).
Manda country_code explícito si tus usuarios no son solo de México, y el teléfono con exactamente 10 dígitos o ya con lada.
Usa una llave por sistema. Si necesitas que dos sistemas cuenten como el mismo origen en reportes, dales el mismo texto de origen al crearlas.
Antes de conectar, pide a quien administra Relevant que pruebe la automatización con el botón Probar con un lead y que te pase el nombre exacto del evento.

¿Necesitas ayuda? Escríbenos a soporte@relevantleads.io y con gusto te apoyamos.

Introducción

Primeros Pasos

IA y Entrenamiento

Gestión de Ventas

WhatsApp y Chats

Captación

Integraciones

Facturación y Cuenta

Antes de empezar

1. La llave

Errores de autenticación

2. Registrar un lead

Campos del cuerpo

Normalización del teléfono

Destino del lead

Respuesta

Deduplicación (idempotencia de registros)

`custom_data`

Qué pasa en Relevant al registrar

3. Avisar de un evento del lead

Campos del cuerpo

Cómo se resuelve el evento

Monto del lead (`amount`)

Límites del `payload`

Respuesta

Idempotencia de eventos

4. Corregir un contacto

Cómo se identifica el contacto

Campos que se pueden cambiar

Cambio de teléfono

Lo que no hace

Respuesta

5. Errores

6. Límites y comportamiento

7. Tiempos de respuesta, timeouts y reintentos

8. Buenas prácticas

​Antes de empezar

​1. La llave

​Errores de autenticación

​2. Registrar un lead

​Campos del cuerpo

​Normalización del teléfono

​Destino del lead

​Respuesta

​Deduplicación (idempotencia de registros)

​custom_data

​Qué pasa en Relevant al registrar

​3. Avisar de un evento del lead

​Campos del cuerpo

​Cómo se resuelve el evento

​Monto del lead (amount)

​Límites del payload

​Respuesta

​Idempotencia de eventos

​4. Corregir un contacto

​Cómo se identifica el contacto

​Campos que se pueden cambiar

​Cambio de teléfono

​Lo que no hace

​Respuesta

​5. Errores

​6. Límites y comportamiento

​7. Tiempos de respuesta, timeouts y reintentos

​8. Buenas prácticas

Antes de empezar

1. La llave

Errores de autenticación

2. Registrar un lead

Campos del cuerpo

Normalización del teléfono

Destino del lead

Respuesta

Deduplicación (idempotencia de registros)

`custom_data`

Qué pasa en Relevant al registrar

3. Avisar de un evento del lead

Campos del cuerpo

Cómo se resuelve el evento

Monto del lead (`amount`)

Límites del `payload`

Respuesta

Idempotencia de eventos

4. Corregir un contacto

Cómo se identifica el contacto

Campos que se pueden cambiar

Cambio de teléfono

Lo que no hace

Respuesta

5. Errores

6. Límites y comportamiento

7. Tiempos de respuesta, timeouts y reintentos

8. Buenas prácticas