> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Custom Field Keys

> Discover the customFields keys actually in use on your Tuco leads, so you can write the right ones in PATCH /api/leads/{id} and in campaign variables.

<Note>
  `customFields` is free-form, so nothing tells you which keys a workspace already uses. This returns
  the ones in use with a count, so you can write the right key in
  [`PATCH /api/leads/{id}`](/api-reference/endpoint/update-lead) instead of guessing and creating a
  near-duplicate.
</Note>

## Authentication

Pass your workspace API key as a Bearer token, or use a Clerk session token.

```bash theme={null}
Authorization: Bearer tuco_xxxxxxxxxxxxx
```

***

## Example

```bash theme={null}
curl "https://app.tuco.ai/api/leads/custom-field-keys" \
  -H "Authorization: Bearer tuco_xxxxxxxxxxxxx"
```

### Success (`200 OK`)

```json theme={null}
{
  "keys": [
    { "name": "Industry", "count": 6 },
    { "name": "Contract Value", "count": 3 },
    { "name": "close_owner_id", "count": 8 }
  ]
}
```

<Warning>
  **This is a sample, not an exhaustive index.** The scan is bounded to keep it cheap on large
  workspaces: at most 2,000 lead documents are inspected and at most 200 keys returned. A rarely-used
  key may be missing from the list — and it still works. `customFields` accepts any key, and
  `{cf:Anything}` resolves at send time whether or not it appears here.
</Warning>

## Response

<ResponseField name="keys" type="object[]">
  Custom-field keys found in the sample.

  <Expandable title="Key fields">
    <ResponseField name="name" type="string">The key, exactly as stored — matching is case-sensitive.</ResponseField>
    <ResponseField name="count" type="number">How many sampled leads carry it.</ResponseField>
  </Expandable>
</ResponseField>

<Note>
  On an internal error this endpoint returns `200` with `{ "keys": [] }` rather than failing — it is
  a discovery aid, and an empty list must not break a page that calls it.
</Note>

***

## Errors

| Status | When | Body |
| - | - | - |
| `400` | Key has no active workspace | `{ "error": "No active workspace" }` |
| `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.