---
title: "Create a custom_field"
method: POST
path: "/v1/custom_fields"
tags: ["Custom Fields"]
---

# Create a custom_field

`POST /v1/custom_fields`

Create a new custom field. book_id is accepted for backwards compatibility but ignored.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `book_id` string — Deprecated. Ignored.
  - `field_key` string, required — Unique field key (lowercase, letters, numbers, underscores only)
  - `display_name` string, required — Human-readable field name
  - `entity_type` 'Household' | 'Person' | 'Contact' | 'Opportunity', required — Entity type this field applies to (Client and Prospect normalize to Household)
  - `field_type` 'text' | 'number' | 'date' | 'boolean' | 'single_select' | 'multi_select' | 'cross_reference', required — Data type of the field
  - `options` object — Field-specific options (required for select fields and cross_reference)
    - `select_options` string[] — Options for single_select and multi_select fields
    - `cross_reference_allowed_target_types` string[] — Allowed target types for cross_reference fields

## Response `201`

custom_field created

- CustomField
  - `id` string, required — The custom field ID
  - `field_key` string, required — The unique field key
  - `display_name` string, required — The human-readable field name
  - `entity_type` 'Household' | 'Person' | 'Contact' | 'Opportunity', required — The entity type this field applies to
  - `field_type` 'text' | 'number' | 'date' | 'boolean' | 'single_select' | 'multi_select' | 'cross_reference', required — The field data type
  - `options` object, nullable — Field-specific options (e.g., select_options for select fields, cross_reference_allowed_target_types for cross_reference)
    - `select_options` string[]
    - `cross_reference_allowed_target_types` string[]

## Other responses

- `400` — bad request - invalid JSON
- `401` — unauthorized - missing or invalid token
- `403` — forbidden
- `422` — unprocessable entity - invalid payload

---

[API](https://skmtc.net/slant/apis/slant-public-api-v1.md) · [All operations](https://skmtc.net/slant/apis/slant-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/slant/slant-public-api-v1/revisions/b56e0d137554/schema)