Miira · leads y WhatsApp v1 vigente
miira.
Crea un lead nuevo en el CRM del workspace a partir de sus datos de contacto. Si ya existe uno que encaja, no lo duplica: contesta `ambiguous` con los candidatos.
Última actualización
POST /api/v1/actions/miira.lead_create- Alcance de la llave
miira.lead_create@1- Permiso del workspace
api.miira.lead_createapagado por defecto
Dos permisos, no uno
Hacen falta las dos cosas: una llave con ese alcance, y que el dueño del workspace haya encendido el permiso. Tener la llave no basta — son dos decisiones de personas distintas.
Petición
| campo | tipo | reglas | |
|---|---|---|---|
submissionId | string (uuid) | obligatorio | |
source | "web_form" | "referral" | "api" | "import" | "event" | "other" | obligatorio | |
name | string | opcional | max 256 |
email | string (email) | opcional | max 320 |
phone | string | opcional | max 40 |
fields | map<string, unknown> | opcional | |
consent | object | opcional |
consent
| campo | tipo | reglas | |
|---|---|---|---|
email | boolean | opcional | |
whatsapp | boolean | opcional | |
source | "api" | "web_form" | "verbal" | "llamada" | "visita" | "imported" | obligatorio |
Respuesta — output cuando status es done
| campo | tipo | reglas | |
|---|---|---|---|
outcome | "created" | "existing" | "ambiguous" | "rejected" | obligatorio | |
clientId | string | null | obligatorio | |
reason | "honeypot" | "invalid_email" | "disposable_email" | "invalid_identity" | null | obligatorio |
Ejemplo
# One request, one idempotency key: retrying with the same key never runs twice.
curl -X POST https://niiko.org/api/v1/actions/miira.lead_create \
-H "Authorization: Bearer nk_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"submissionId": "01890a5d-ac96-774b-bcce-b302099a8057",
"source": "web_form"
}'
# 200 → done · 202 → pending_approval (a person signs later) · 4xx → refused, with a named reasonPor qué puede negarse
Cada motivo dice quién puede arreglarlo y cómo. Con motivo stale, detail.message dice qué hacer.
honeypotinvalid_emaildisposable_emailinvalid_identityleads_exceeded
En los clientes
| @vorluno/niiko-sdk | niiko.createLead() |
| niiko (Python) | niiko.create_lead() |
| niiko-cli | niiko run miira.lead_create |
| n8n-nodes-niiko | miiraLeadCreate |
| niiko-mcp-server | miira_lead_create |