IdiomaENES
WelcomeAI
Integraciones

Enviar un lead desde tu propio código

Publica un lead que recogiste en otro sitio en la misma lista, con las mismas rutas de CRM y los mismos webhooks.

Actualizado 2026-09-11Ver .md

Qué hace

POST /api/v1/leads pone un lead en la lista del espacio de trabajo desde donde sea: un formulario de tu propio sitio, un checkout, una llamada que alguien anotó después. Cae en el mismo lugar que un lead del widget, así que se disparan las mismas rutas de CRM, los mismos webhooks salientes, y aparece en la misma lista y en la misma exportación.

Qué necesitas antes de empezar

  • Una clave de API con el permiso `leads:write`. No puede leer la lista de leads; eso es leads:read.
  • Un espacio de trabajo en un plan que incluya la API.

Autenticación

Authorization: Bearer wai_live_…, por HTTPS. La clave se muestra una sola vez al crearla.

La petición

bash
curl -X POST https://app.welcomeai.dev/api/v1/leads \
  -H "Authorization: Bearer wai_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "phone": "+34 600 111 222",
    "page_url": "https://acme.com/precios",
    "fields": { "company": "Analytical Engines", "budget": "5000" },
    "attribution": { "utm_source": "newsletter", "utm_campaign": "primavera", "gclid": "Cj0KC…" }
  }'
Campo
email, phone
Al menos uno es obligatorio. Un lead al que nadie puede contactar es una fila, no un lead, y todos los destinos de CRM lo rechazan igual.
name
Se parte en nombre y apellido igual que lo hace un formulario enviado. Si ya los tienes separados, manda first_name / last_name.
fields
Las respuestas de tu propio formulario. Las claves que quieras; aparecen en el lead y se pueden asignar a un campo del CRM.
page_url
Tiene que ser una URL http o https.
attribution
Parámetros UTM, ids de clic de anuncios, referrer, landing_page. Lo que no sea una de las claves que conocemos se descarta, no se rechaza.
widget_id, form_config_id
Opcionales. Se ignoran si no pertenecen a tu espacio de trabajo.

La respuesta

json
{ "ok": true, "lead_id": "ld_9Kq2…", "recurring": false, "submissions": 1 }

`201` para alguien nuevo, `200` para alguien que volvió. Una dirección de correo es un lead por espacio de trabajo: publicar a la misma persona otra vez actualiza el lead que ya tienes en vez de crear un segundo, submissions cuenta cuántas veces se puso en contacto, y la lista lo marca como Recurrente.

La combinación rellena huecos y nunca borra nada. Si la semana pasada dejó un teléfono y esta vez solo el correo, el teléfono se queda. Una respuesta nueva a la misma pregunta gana; una respuesta vieja a una pregunta que no volviste a enviar sobrevive. El estado y las notas del lead no se tocan nunca: alguien pudo haberlo movido a Contactado y haber escrito ahí, y que la persona vuelva no es motivo para deshacerlo.

Errores habituales

`400 A lead needs an email or a phone number.` Manda uno de los dos.

`400 page_url: must be an http or https URL.` El campo se renderiza como enlace en la lista de leads, así que solo se aceptan esos dos esquemas.

`403 This key does not have the "leads:write" scope.` Los permisos se eligen al crear la clave y no se pueden agregar después. Crea una clave nueva.

`429` El presupuesto diario de API del plan. Es una ventana móvil de 24 horas por clave.

Para qué se usa

Un formulario de contacto que ya existe y que nadie quiere rehacer. Una consulta telefónica anotada a mano para que llegue al CRM con el resto. Un checkout que además debería crear un lead. Traer una lista antigua una vez, para que las rutas de CRM pasen por ella.

Cómo comprobar que funciona

  1. Publica uno y lee el lead_id que devuelve.
  2. Leads lo muestra, con API como origen.
  3. Si el espacio tiene una ruta de CRM, el registro de envíos tiene una fila en pocos segundos.
  4. Publica la misma dirección otra vez: la respuesta es 200 con "recurring": true, y la lista sigue teniendo un solo lead con el distintivo Recurrente.