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

# Custom fields

> Pass and read custom field values in API v2 requests and responses

# Custom fields

Entities that support custom fields use the `cf_` prefix. Send values as top-level keys on create and update; responses return the same keys on the resource object — not inside a `customFields` property.

## Supported resources

| Resource   | Endpoints                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------- |
| Contacts   | `/api/v2/contacts`                                                                            |
| Companies  | `/api/v2/companies`                                                                           |
| Deals      | `/api/v2/deals`                                                                               |
| Quotations | `/api/v2/quotations`                                                                          |
| Tasks      | `/api/v2/tasks`                                                                               |
| Projects   | `/api/v2/projects`                                                                            |
| Products   | `/api/v2/products` (accept `cf_*` on create/update; not returned on the product resource yet) |

## Naming convention

Custom field keys are derived from the field label in Heffl:

1. Lowercase the label
2. Replace spaces with underscores
3. Prefix with `cf_`

| Field label in Heffl | API key           |
| -------------------- | ----------------- |
| Industry             | `cf_industry`     |
| Company Size         | `cf_company_size` |
| Lead Score           | `cf_lead_score`   |

## Example — create

```bash theme={null}
curl -X POST https://api.heffl.com/api/v2/companies \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme LLC",
    "email": "hello@acme.example",
    "cf_industry": "Technology",
    "cf_lead_source_detail": "Webinar signup"
  }'
```

## Example — update

On update, custom fields are merged with existing values. Omitted `cf_*` keys are left unchanged.

```bash theme={null}
curl -X PATCH https://api.heffl.com/api/v2/contacts/clt_abc123 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cf_industry": "SaaS",
    "cf_lead_score": 85
  }'
```

## Responses

Custom field values appear as top-level `cf_*` keys on the resource (in list `data` items and on create/update/get responses). There is no `customFields` object in API v2.

```json theme={null}
{
  "id": "clt_abc123",
  "name": "Acme LLC",
  "cf_industry": "Technology",
  "cf_lead_source_detail": "Webinar signup"
}
```

Deal example:

```json theme={null}
{
  "id": "deal_abc123",
  "title": "Enterprise plan",
  "cf_priority": "high"
}
```

Configured fields may appear with `null` when unset (especially on list rows).

## Validation

* Only documented fields and `cf_*` keys are allowed — unknown fields return a validation error
* Field types must match the custom field definition in your workspace (text, number, date, etc.)

Configure custom fields in **Settings → Custom fields** in the Heffl app.

## Discover field keys via API

List definitions (key, label, type, allowed values) before writing integrations:

```bash theme={null}
curl "https://api.heffl.com/api/v2/custom-fields?entity=deals&pipelineId=dpl_abc123" \
  -H "x-api-key: YOUR_API_KEY"
```

Supported `entity` values: `contacts`, `companies`, `deals`, `tasks`. For deals, pass `pipelineId` to include pipeline-scoped fields.