# Custom fields — define and use

> **TL;DR for agents:** Define: `POST /api/custom-fields {entity, name, fieldKey, type}`. Set value on an entity: `POST /api/custom-fields/params/:entity/:entityId`. Read in entity payload: `customFields` (JSON map for company; relation array for contact/lead/account). Show up in exports automatically as `cf_<fieldKey>` columns.

## Define a new custom field (per entity)

Scope: `customfields:write`. `entity` ∈ {COMPANY, CONTACT, LEAD, EMAIL_ACCOUNT}. `type` ∈ {TEXT, NUMBER, DATE, BOOL, SELECT, MULTISELECT, URL, EMAIL, PHONE, JSON}.

```bash
curl -s -X POST "https://api.live-direct-marketing.online/api/custom-fields" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"entity":"LEAD","name":"Engineer score","fieldKey":"engineer_score","type":"NUMBER"}'
```

## List existing definitions

```bash
curl -s "https://api.live-direct-marketing.online/api/custom-fields?entity=LEAD" \
  -H "Authorization: Bearer $LDM_KEY"
```

## Set value on a specific entity (legacy params endpoint, idempotent)

```bash
curl -s -X POST "https://api.live-direct-marketing.online/api/custom-fields/params/LEAD/$LEAD_ID" \
  -H "Authorization: Bearer $LDM_KEY" -H "Content-Type: application/json" \
  -d '{"engineer_score": 8, "qualified_at": "2026-05-07"}'
```

For COMPANY this writes into the `customFields` JSON column (auto-creates schema). For CONTACT/LEAD/EMAIL_ACCOUNT it upserts into the relation table.

## Verify in exports

Once defined, `GET /api/exports/columns?entity=leads` includes a Custom group with `cf_engineer_score`. The export job will include that column when requested.

```bash
curl -s "https://api.live-direct-marketing.online/api/exports/columns?entity=leads" \
  -H "Authorization: Bearer $LDM_KEY" | jq '.groups[] | select(.group=="Custom")'
```