Miira · leads & WhatsApp v1 current
miira.
Creates a new lead in the workspace CRM from its contact details. If a matching one already exists it is not duplicated: the reply is `ambiguous` with the candidates.
Last updated
POST /api/v1/actions/miira.lead_create- Key scope
miira.lead_create@1- Workspace permission
api.miira.lead_createoff by default
Two permissions, not one
Both are needed: a key with that scope, and the workspace owner having switched the permission on. Holding the key is not enough — they are two decisions made by different people.
Request
| field | type | rules | |
|---|---|---|---|
submissionId | string (uuid) | required | |
source | "web_form" | "referral" | "api" | "import" | "event" | "other" | required | |
name | string | optional | max 256 |
email | string (email) | optional | max 320 |
phone | string | optional | max 40 |
fields | map<string, unknown> | optional | |
consent | object | optional |
consent
| field | type | rules | |
|---|---|---|---|
email | boolean | optional | |
whatsapp | boolean | optional | |
source | "api" | "web_form" | "verbal" | "llamada" | "visita" | "imported" | required |
Response — output when status is done
| field | type | rules | |
|---|---|---|---|
outcome | "created" | "existing" | "ambiguous" | "rejected" | required | |
clientId | string | null | required | |
reason | "honeypot" | "invalid_email" | "disposable_email" | "invalid_identity" | null | required |
Example
# 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 reasonWhy it may refuse
Each reason names who can fix it and how. With reason stale, detail.message says what to do.
honeypotinvalid_emaildisposable_emailinvalid_identityleads_exceeded
In the clients
| @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 |