Capture a lead
For website and landing-page forms. Adds the enquiry as a new lead, or, when the organization already has a lead with this phone number or email (matched ignoring case), fills in that lead instead: only fields it has empty are filled, and values that differ from what your team entered are kept and listed on the lead’s timeline. The owner, stage and pipeline of an existing lead are never changed, and an archived lead is not changed at all (the enquiry is noted on its timeline). A new lead starts in the starting stage and gets an owner from the organization’s assignment rules. Every capture is recorded on the lead’s timeline, naming the API key that sent it.
Server to server only: call it from your website’s server (a route handler, a server action, PHP), never from browser JavaScript, where the key would be visible to anyone. There is no CORS support on purpose.
Retries are safe: send an Idempotency-Key header (or an externalId), and a repeat within 24 hours returns the first result without capturing again.
Scope: leads.capture or leads.write.
Authorizations
An organization API key, created in Settings → Connections → API keys. Keys start with mk_live_. Marro stores only a hash of a key, so it is shown once, when it is created: copy it then. Revoking a key ends its access at once. To replace a key without downtime, create the new one, switch your server to it, then revoke the old one. Changes made with a key appear on the lead’s timeline as made by the person who created the key, via the API. Scopes: leads.read (Read leads), leads.write (Create and update leads), leads.capture (Capture leads).
Headers
Optional. A unique value per submission, such as a UUID; remembered per API key. A retry with the same key within 24 hours returns the first result, with Idempotent-Replayed: true; the same key with a different body is refused.
1 - 200Body
The person’s name.
1 - 200With the country code, e.g. +919812345678. Numbers without one are read as Indian. Used, with email, to find a lead the organization already has.
6 - 32Also used to find an existing lead when the phone number does not match one.
254The source’s name, e.g. "Website" (the default) or "Google Ads". It must be one of the organization’s active sources (matched ignoring case; list them with GET /api/v1/lead-sources). Any other name is recorded as "Website", so a website key cannot fill the organization’s source list.
1 - 60For a new lead, the pipeline it starts in (IDs from GET /api/v1/pipelines); it lands in that pipeline’s starting stage. Defaults to the organization’s default pipeline. Never moves an existing lead.
x <= 2147483647Free text shown on the lead’s timeline with this enquiry, such as the visitor’s message.
5000More details, by field key: the organization’s built-in and custom lead fields (GET /api/v1/lead-fields). Values are checked with the same rules as the CRM’s forms: dropdowns take one of their options (value or label), numbers, dates (YYYY-MM-DD) and yes/no fields are parsed. An unknown key is refused with the list of valid keys. On an existing lead only empty fields are filled.
Where the enquiry came from. Shown on the lead’s timeline.
Your own ID for this submission. A resend with the same externalId (per API key) within 24 hours returns the first result instead of capturing again.
1 - 200Response
The organization already had this lead; it was found and any empty fields filled in. Location points at it.