---
title: "Create a customer-created subscriber field."
method: POST
path: "/fields"
tags: ["Fields"]
---

# Create a customer-created subscriber field.

`POST /fields`

## Request

- Base URL: `https://api.maildroppa.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maildroppa.com/fields`
- Auth: API key in header `X-API-Key`

Creates a non-built-in subscriber field. If no personalization tag name is provided, the backend derives an available lowercase ASCII personalization tag name from the field label. SINGLE_CHOICE and MULTI_CHOICE require options; scalar fields must not include options.

## Request body

- AddField: Subscriber field to create. Choice fields require options; non-choice fields must not include options.
  - `personalizationTagName` string: Optional stable lowercase ASCII personalization tag name used in imports, forms, personalization, and subscriber field value updates. Leave empty to let the backend derive an available name from the field label.
  - `label` string: Human-readable field label shown in the app.
  - `fieldType` 'TEXT' | 'LONG_TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_CHOICE' | 'MULTI_CHOICE'
  - `required` boolean: Whether subscribers must provide a value for this field in signup and subscriber edit workflows.
  - `internal` boolean: Whether this field is hidden from subscriber-facing forms and subscriber profile editing.
  - `options` string[]: Option labels for SINGLE_CHOICE and MULTI_CHOICE fields. Must be empty for scalar fields.

## Response `200`

Field created.

- Field: Subscriber field definition.
  - `type` 'BUILT_IN' | 'CUSTOM'
  - `builtInField` 'EMAIL' | 'FIRST_NAME'
  - `fieldId` string, uuid
  - `personalizationTagName` string: Stable personalization tag name used in imports, forms, personalization, and subscriber field value updates.
  - `label` string: Human-readable field label shown in the app.
  - `fieldType` 'TEXT' | 'LONG_TEXT' | 'EMAIL' | 'NUMBER' | 'DATE' | 'BOOLEAN' | 'SINGLE_CHOICE' | 'MULTI_CHOICE'
  - `required` boolean: Whether subscribers must provide a value for this field in signup and subscriber edit workflows.
  - `internal` boolean: Whether this field is hidden from subscriber-facing forms and subscriber profile editing.
  - `active` boolean: False when a customer-created field has been archived.
  - `position` integer: Ordering position in the field schema.
  - `options` FieldOption[]: Selectable options for SINGLE_CHOICE and MULTI_CHOICE fields.
    - `id` string, uuid
    - `label` string: Human-readable option label.
    - `position` integer: Ordering position within the field options.
    - `active` boolean: Whether the option can still be selected for new subscriber field values.

## Other responses

- `400`: Invalid field data, duplicate personalization tag name, or field limit reached.
- `401`: Not Authorized
- `403`: Not Allowed
- `428`: Accept the customer agreements in the app before using API keys.

---

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