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:

Lowercase the label
Replace spaces with underscores
Prefix with cf_

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

Example — create

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": "[email protected]",
    "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.

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.

{
  "id": "clt_abc123",
  "name": "Acme LLC",
  "cf_industry": "Technology",
  "cf_lead_source_detail": "Webinar signup"
}

Deal example:

{
  "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:

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.

Overview

Objects

Reference

Custom fields

Custom fields

Supported resources

Naming convention

Example — create

Example — update

Responses

Validation

Discover field keys via API

​Custom fields

​Supported resources

​Naming convention

​Example — create

​Example — update

​Responses

​Validation

​Discover field keys via API

Custom fields

Supported resources

Naming convention

Example — create

Example — update

Responses

Validation

Discover field keys via API