Inbound lead webhooks

Any external site can create a lead in Ikigai by POSTing JSON to a form submit URL. Each web form you create in the CRM gets its own unguessable URL — no API key is needed on the public side, so the endpoint is safe to call from a browser.

Set up a web form

1. Open Settings → Integrations → Web forms («Веб-формы» / «Веб-форми» in the localized interface) and create a form.
2. Pick the pipeline and stage new submissions should land in. If you leave them empty, the workspace default pipeline is used.
3. Open the form's Embed tab. It shows the submit URL — POST /api/v1/forms/<form-id>/submit — plus a ready-to-paste HTML snippet with a hidden anti-spam field and a script that captures UTM parameters from the page URL automatically.

The payload

Send Content-Type: application/json with any of these fields:

Field	Notes
name (or firstName + lastName)	Contact name
email, phone, phoneCountry	Identifiers; phone is normalized to E.164 using the 2-letter country hint
companyName	Linked or created as a company
message, service	Free text saved with the deal
utm	Object with source, medium, campaign, term, content
fbclid, gclid, ttclid	Ad click IDs for attribution
landingReferrer	The page the visitor came from
hp_field	Honeypot — must stay empty; bots that fill it are silently discarded

The response tells you what happened:

{ "ok": true, "formId": "…", "dealId": "…", "contactId": "…", "duplicate": false }

What happens on our side

1. Email is lowercased and the phone converted to E.164.
2. If a contact with the same email or phone already exists, it is reused — no duplicate contact is created.
3. A deal is created in the form's pipeline and stage, carrying the UTM values and click IDs.
4. The standard deal.created event fires, so lead distribution and your automations run exactly as for any other lead.

Duplicate and abuse protection

• Honeypot: a filled hp_field is accepted with a fake success and dropped.
• Duplicate window: a repeat submission with the same contact data inside the form's configured window returns the existing deal with "duplicate": true instead of creating a second one.
• Rate limit: 20 submissions per minute per form per IP address.
• CORS: the submit endpoint answers cross-origin requests, so the snippet works on any domain.

Building a server-to-server integration instead of a website form? Use the public REST API with an API key — it gives you full create/update access and the same automation events.