Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

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.

Required string length: 1 - 200

Body

application/json
name
string
required

The person’s name.

Required string length: 1 - 200
phone
string
required

With the country code, e.g. +919812345678. Numbers without one are read as Indian. Used, with email, to find a lead the organization already has.

Required string length: 6 - 32
email
string

Also used to find an existing lead when the phone number does not match one.

Maximum string length: 254
source
string

The 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.

Required string length: 1 - 60
pipelineId
integer

For 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.

Required range: x <= 2147483647
notes
string

Free text shown on the lead’s timeline with this enquiry, such as the visitor’s message.

Maximum string length: 5000
fields
object

More 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.

attribution
object

Where the enquiry came from. Shown on the lead’s timeline.

externalId
string

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.

Required string length: 1 - 200

Response

The organization already had this lead; it was found and any empty fields filled in. Location points at it.

lead
object
required