---
title: "List custom field definitions"
method: GET
path: "/v1/custom-fields"
tags: ["Contacts"]
---

# List custom field definitions

`GET /v1/custom-fields`

## Request

- Base URL: `https://api.automatedclientacquisition.com`
- URL: `https://api.automatedclientacquisition.com/v1/custom-fields`
- Auth: HTTP bearer

The schema behind `crm_contacts.custom_fields` — which keys are valid,
what type each expects, and which values a `select` accepts. Read this
before writing `custom_fields`, or you are guessing against an
unversioned blob.

Unpaginated: definitions number in the handful, and you always want them
whole. Read-only over the API — changing a definition reshapes every
contact already carrying the key, so it is a dashboard operation
(Settings → Custom Fields).

## Response `200`

Every custom field definition in your organization, in display order.

- object
  - `success` boolean
  - `data` CustomFieldDefinition[]
    - `id` string, uuid
    - `field_key` string: The key inside `crm_contacts.custom_fields`, and the merge variable name in sequences.
    - `display_name` string: Human label shown in the dashboard.
    - `field_type` string: e.g. `text`, `number`, `date`, `select`, `boolean`. Values are stored as JSON, not coerced on write.
    - `options` string[], nullable: Allowed values when `field_type` is a select.
    - `is_required` boolean, nullable: Enforced by the dashboard form, not by the API.
    - `validation_rules` object, nullable
    - `default_value` string, nullable
    - `description` string, nullable
    - `display_order` integer, nullable
    - `is_visible_in_list` boolean, nullable
    - `is_searchable` boolean, nullable
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable

## Other responses

- `401`: Missing, invalid or revoked token.

---

[API](https://skmtc.dev/automatedclientacquisition/apis/aca-api.md) · [All operations](https://skmtc.dev/automatedclientacquisition/apis/aca-api/llms.txt) · [OpenAPI document](https://skmtc.dev/automatedclientacquisition/apis/aca-api/revisions/8f3e3b141311?raw)