Hoy los leads vienen exclusivamente de formularios Meta Lead Ads de una Página conectada — se leen, no se crean por API.
POST /leads). Si quieres capturar un contacto a partir de un mensaje de WhatsApp o un comentario, guárdalo en tu propio CRM al recibir el webhook — ver Webhooks./accounts/:id/lead-forms/accounts/:id/leads?formId=…/accounts/:id/lead-forms{ name, locale?, questions[], privacy_policy:{url,link_text}, context_card?, thank_you_page?, follow_up_action_url? }. Meta no permite editarlo después de creado./accounts/:id/lead-forms/:formIdquestions)./accounts/:id/lead-forms/:formId/test-webhooklead.received de muestra (field_data derivado de las preguntas reales del form) a tus webhooks. Determinístico y no toca Meta — sirve para probar tu receptor sin esperar un lead real. Devuelve { ok, webhooksNotified }.Para crear/borrar test leads reales en Meta (que aparecen en el Ads Manager), usa el Lead Ads Testing Tool ↗ de Meta — su API no dispara webhook ni permite borrarlos.
El lead en sí vive en Meta y es inmutable. Encima puedes guardar tu propia capa de estado —en qué punto del embudo está, cuánto vale, una nota— sin sacarlo a otro sistema.
/accounts/:id/lead-states/accounts/:id/lead-states/:leadId{ status?, value?, note? } — value es número o null, note es texto o null. Un status fuera de la lista permitida responde 400 con los valores válidos en el mensaje.Cuando alguien envía un Lead Ads de Meta, el sistema lo recoge solo y dispara lead.received por webhook — no necesitas hacer polling de /leads si ya tienes un webhook suscrito a ese evento.
{
"event": "lead.received",
"id": "whd_…", "ownerId": "…", "profileId": "prof_…",
"data": {
"formId": "…",
"lead": {
"id": "…", "created_time": "…", "form_id": "…", "platform": "…", "is_organic": false,
"ad_id": "…", "ad_name": "…",
"adset_id": "…", "adset_name": "…",
"campaign_id": "…", "campaign_name": "…",
"field_data": [{ "name": "full_name", "values": ["…"] }]
}
}
}El lead va anidado: el conjunto de anuncios está en data.lead.adset_id, no en la raíz del cuerpo. Los campos de anuncio (ad_id, adset_id, campaign_id y los nombres) vienen vacíos o ausentes cuando el lead es orgánico (is_organic: true) o salió de una vista previa del anuncio. El evento de prueba (test-webhook) los trae con valores falsos que empiezan con test_.
curl "https://zoosial.com/accounts/acc_456/leads?formId=form_789" \ -H "Authorization: Bearer $SC_API_KEY"