# Create Lead Field

> Define a lead custom field and its type.

> Documentation index: https://www.foxreach.io/docs/llms.txt lists every page of these docs. Each page is also served as Markdown: add `.md` to its URL.

`POST` https://api.foxreach.io/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.

**Request example**

```bash cURL
curl -X POST "https://api.foxreach.io/api/v1/lead-fields" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"key": "Industry", "type": "select", "options": ["SaaS", "Agency"]}'
```

**Response example**

```json
{
  "data": { "id": "clf_abc123", "key": "Industry", "type": "select", "options": ["SaaS", "Agency"], "position": 1, "defined": true, "leadCount": 0 }
}
```

## 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](https://www.foxreach.io/docs/rate-limiting).
