---
title: "Create a contact field"
method: POST
path: "/v1/fields"
tags: ["Contact Fields"]
---

# Create a contact field

`POST /v1/fields`

Creates a custom field definition (`{ fieldName, fieldType: "string" | "number" | "date" | "bool" }`). Returns `201` with the bare definition. (Contact upserts also auto-create unknown fields — explicit creation is for pinning the type up front.)

## Headers

- `Idempotency-Key` string

## Request body

- FieldsPostRequest
  - `fieldName` string, required
  - `fieldType` 'string' | 'number' | 'date' | 'bool', required

## Response `201`

Created.

- ContactFieldDefinition
  - `fieldName` string, required
  - `fieldType` 'string' | 'number' | 'date' | 'bool', required
  - `label` string
  - `isCore` boolean
  - `isFilterable` boolean
  - `isSortable` boolean
  - `isSearchable` boolean
  - `coverage` object
    - `percent` integer, required
    - `approximate` boolean, required
    - `topValues` object[], required
      - `value` string, required
      - `count` integer, required
      - `percent` integer, required
    - `dominantValue` string

## Other responses

- `400` — The request body or query string was invalid (unknown key, wrong type, or missing required field). Strict schemas reject unknown keys — including `brandId`, which is always resolved from the API key.
- `401` — The API key was missing, invalid, or revoked.
- `403` — The caller does not have the required `contacts` permission.
- `409` — The field already exists with a different `fieldType` — redefinition is rejected to avoid corrupting stored values (re-creating with the SAME type is idempotent). An idempotency-key replay with a different body also returns `409`.
- `422` — The field name collides with a core column.
- `429` — The request hit the rolling rate limit window.
- `500` — Unexpected internal error.

---

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