Add a lead field
POST/v1/agents/:agentId/lead-fields
x-scope: "leads:write"
Adds a custom field to the agent's lead form, after its other custom fields, shown in the
dashboard's table and form. The built-in status, assigned_to, notes and created_at
come last on an agent whose fields were never reordered, so the new field goes before
them. The AI's lead capture starts collecting it in the background, usually within a
minute: the label tells the AI what to ask for, and required makes it treat the field
as needed before it saves a lead. A reserved key is 422 invalid_request (see key); any
other key the agent already has, built-in fields included, is 409 field_key_taken; an
agent that already has 50 custom fields is 422 lead_field_limit_reached.
Request
Responses
- 201
- 401
- 403
- 404
- 409
- 413
- 422
- 429
- 500
- 503
The lead field.
Response Headers
Correlation id for this request — paste into support tickets.
Authentication failed. Single code (invalid_api_key) covers every
sub-case: missing header, wrong scheme, malformed, unknown, revoked or
expired key. The message field disambiguates for humans debugging.
One exception: when the key could not be checked because of a server-side
fault, the status is still 401 but type is internal_error and code
is internal_server_error; retry with backoff.
Response Headers
Correlation id for this request — paste into support tickets.
Authenticated, but not allowed: insufficient_scope (the key lacks the scope in this
operation's x-scope) or agent_not_authorized (the key is limited to other agents).
Response Headers
Correlation id for this request — paste into support tickets.
agent_not_found when the agent is not one of your company's agents (the API never confirms
whether another company's agent exists); endpoint_not_found for a path or method no
endpoint serves, including an id that is not a UUID.
Response Headers
Correlation id for this request — paste into support tickets.
The agent already has a lead field with this key, built-in fields
included. Nothing was created. A create retried after a lost response
lands here too: read listLeadFields and carry on.
Response Headers
Correlation id for this request — paste into support tickets.
The request body is larger than 1 MB.
Response Headers
Correlation id for this request — paste into support tickets.
invalid_request_body when the body isn't valid JSON, a field has the wrong type or
format, or a field breaks a limit in its schema; param names the field.
invalid_request for a reserved key (see key), and lead_field_limit_reached when
the agent has no room for another custom field.
Response Headers
Correlation id for this request — paste into support tickets.
Per-key rate limit hit. Default is 60/min/key; an endpoint with an
x-rate-limit-per-minute of its own counts in a budget of its own
(today listWhatsAppTemplates, which allows 10/min/key, and
sendConversationMessage, which allows 20/min/key), and its 429
reports that limit in X-RateLimit-Limit. Retry-After tells you when to retry;
X-RateLimit-Reset is the Unix timestamp of the next window.
Per-success-response
X-RateLimit-*headers are a known gap; on 2xx responses these headers are NOT currently emitted. Customers should rely on 429 +Retry-Afterfor backoff signals.
Response Headers
Correlation id for this request — paste into support tickets.
Seconds to wait before retrying.
The per-minute request limit of the endpoint called. Every key has the same limits today.
Remaining requests in the current window. 0 on rejection.
Unix timestamp at which the current window resets.
Unexpected server-side failure. Retry with exponential backoff. If
the failure persists, send us the correlation_id.
Response Headers
Correlation id for this request — paste into support tickets.
Mojeeb couldn't check access because of a temporary fault: the key's,
or on assignLead and assignConversation the teammate's. Nothing was
changed. Retry with backoff.
Response Headers
Correlation id for this request — paste into support tickets.