Skip to contentSkip to navigation

Create Lead Field

Define a lead custom field and its type.

POST /api/v1/lead-fields

Values stay in each lead's customFields under key. Once a field is defined, the FoxReach app shows the right input for it and checks values entered there.

Request Body

key string body required

1 to 64 characters, no {, } or |, and not a built-in field name such as first_name or company. Unique per workspace (409 otherwise).

type string body

text (default), number, date (YYYY-MM-DD), url or select.

options string[] body

Required for select: up to 50 choices of up to 100 characters. Duplicates are removed.

Response

Returns 201 with the field in data.

data object
Field object
id string
Field id, or null for a key leads carry without a definition.
key string
The key in each lead's customFields.
type string
text, number, date, url or select.
options string[]
Choices of a select field; empty for other types.
position integer
Order in forms and Settings; null when not defined.
defined boolean
false for a key found on leads that nobody defined yet (treated as text).
leadCount integer
Leads with a non-empty value.

Rate Limit

  • 120 requests per minute, shared by every write call in your workspace. Fixed 60-second window.
  • Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (write).
  • A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns, see Rate Limiting.

Was this page helpful?