Custom field definitions API

The endpoints under /api/custom-fields/ manage the schema for custom fields — the field definitions admins create in the settings UI. The actual values you store on individual records use each entity's regular endpoint (see Custom fields feature).

Permissions

• List / read — any authenticated user (the frontend needs definitions to render detail-page forms).
• Create / update / delete — admin role only.

List definitions

GET /api/custom-fields/?target_model=Lead&active_only=true
Authorization: Bearer <token>

{
  "definitions": [
    {
      "id": 17,
      "target_model": "Lead",
      "key": "industry",
      "label": "Industry",
      "field_type": "dropdown",
      "options": [
        { "value": "saas", "label": "SaaS" },
        { "value": "manufacturing", "label": "Manufacturing" }
      ],
      "is_required": false,
      "is_filterable": true,
      "is_active": true,
      "display_order": 0
    }
  ]
}

Query parameters:

• target_model — filter by entity name (Lead, Account, Contact, Opportunity, Task, Case, Invoice, Estimate, RecurringInvoice).
• active_only=true — exclude soft-deleted definitions.

Create

POST /api/custom-fields/
{
  "target_model": "Lead",
  "key": "industry",
  "label": "Industry",
  "field_type": "dropdown",
  "options": [
    { "value": "saas", "label": "SaaS" },
    { "value": "manufacturing", "label": "Manufacturing" }
  ],
  "is_required": false,
  "is_filterable": true,
  "display_order": 0,
  "is_active": true
}

Constraints:

• key must match ^[a-z][a-z0-9_]*$ and be unique per (org, target_model).
• options is required only when field_type is dropdown.
• target_model must be one of the nine supported entities.

Update

PUT /api/custom-fields/<id>/
{ "label": "Industry Vertical", "options": [ … ] }

Immutable fields: key and field_type cannot change after creation. The API returns 400 if either is in the body.

Delete (soft)

DELETE /api/custom-fields/<id>/

Sets is_active=false. Existing values on records are preserved; new writes for the deactivated key are rejected as unknown. Reactivate with PATCH { "is_active": true }.

Errors

{
  "error": true,
  "errors": {
    "key": "must match ^[a-z][a-z0-9_]*$",
    "options": "Dropdown fields require a non-empty list of {value, label} pairs"
  }
}

See Errors for the full error response shape.