---
title: "Create Global Custom Field"
method: POST
path: "/persons/custom_field"
tags: ["persons"]
---

# Create Global Custom Field

`POST /persons/custom_field`

## Request body

- CreatePersonListCustomFieldInput
  - `name` string, required
  - `type` 'TEXT' | 'NUMBER' | 'DATE' | 'SINGLE_SELECT' | 'MULTI_SELECT' | 'PERSON' | 'WEBSITE' | 'CHECKBOX' | 'STATUS' | 'RECORD_REFERENCE', required
  - `metadata` union
    - SelectListCustomFieldMetadataInputSchema
      - `options` SelectListCustomFieldValueOptionInputSchema[]
        - `urn` string
        - `name` string, required
        - `color` string, required
        - `default` boolean, nullable
    - NumberListCustomFieldMetadata
      - `format` 'NUMBER' | 'PERCENT' | 'US_DOLLAR'
    - DateListCustomFieldMetadata
      - `format` 'MM_DD_YYYY' | 'DD_MM_YYYY' | 'YYYY_MM_DD'
    - PersonListCustomFieldMetadata
      - `mode` 'SINGLE' | 'MULTIPLE', required
    - RecordReferenceListCustomFieldMetadata
      - `record_type_urn` string, required
      - `allow_multiple` boolean, required
      - `mode` string, nullable
  - `default_value` union
    - CheckboxListCustomFieldValue
      - `value` boolean, nullable
    - NumberListCustomFieldValue
      - `value` number, nullable
    - TextListCustomFieldValue
      - `value` string, nullable
    - PersonListCustomFieldDefaultValue
      - `value` string[]
      - `mode` 'FIXED_URN' | 'ADDED_BY_USER', required
    - DateListCustomFieldDefaultValue
      - `value` string, nullable
      - `mode` 'FIXED_DATE' | 'CREATED_AT', required
    - WebsiteListCustomFieldValue
      - `value` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

> 11 revisions in range; 2 could not be searched.

- **2026-08-19** `fbef1ba78f96` — 4 breaking
  - removed `#/components/schemas/EmailListCustomFieldValue` from the `default_value` request property `anyOf` list
  - removed `#/components/schemas/OwnerListCustomFieldMetadata` from the `metadata` request property `anyOf` list
  - removed the enum value `EMAIL` of the request property `type`
  - removed the enum value `OWNER` of the request property `type`
- **2026-08-19** `2100d53a6676` — 4 info
  - added `#/components/schemas/EmailListCustomFieldValue` to the `default_value` request property `anyOf` list
  - added `#/components/schemas/OwnerListCustomFieldMetadata` to the `metadata` request property `anyOf` list
  - added the new `EMAIL` enum value to the request property `type`
  - added the new `OWNER` enum value to the request property `type`
- **2026-07-26** `fcf35c98e097` — 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status

[Change history](https://skmtc.dev/harmonic/apis/harmonic-ai-public-api/changes/persons/custom_field/post.md)

---

[API](https://skmtc.dev/harmonic/apis/harmonic-ai-public-api.md) · [All operations](https://skmtc.dev/harmonic/apis/harmonic-ai-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/harmonic/harmonic-ai-public-api/revisions/6b871b842c2d/schema)