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

# Create a custom field

`POST /v1/custom-fields`

## Request

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

Creates a workspace-scoped custom-field definition.

## Headers

- `Idempotency-Key` string

## Request body

- CustomFieldUpsertRequest
  - `label` string, required
  - `type` 'Text' | 'Number' | 'Date' | 'Select (Dropdown)' | 'Single Select' | 'Multi Select' | 'Text Area' | 'Checkbox', required
  - `settings` object
    - `options` string[]

## Response `201`

Custom field created

- object
  - `data` CustomField, required
    - `self` string, required: Stable relative Public API path for retrieving this resource.
    - `id` string, required
    - `label` string, required
    - `type` string, required
    - `settings` object, required
      - `options` string[], required
    - `personalization_token` string, required: The exact ready-to-use token for this custom field. Copy it into an email subject or body text node and replace only the fallback text when needed. This value is computed from the current field label and is not stored separately.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: Request is invalid

---

[API](https://skmtc.dev/mailrith/apis/mailrith-api.md) · [All operations](https://skmtc.dev/mailrith/apis/mailrith-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailrith/apis/mailrith-api/revisions/41f09536f2da?raw)