---
title: "POST (create) a custom_field"
method: POST
path: "/contact_custom_fields"
tags: ["Contacts Custom Fields"]
---

# POST (create) a custom_field

`POST /contact_custom_fields`

Custom fields are extra data fields you create to store additional information about your contacts, such as preferences, membership levels, and interests. Use custom fields to organize contacts, send personalized email campaigns, and to identify a targeted audience for a specific campaign. Custom fields types include text, number, date, drop-down lists, radio buttons, and checkboxes. A user can configure up to 100 `custom_fields` in their account.

## Request body

- CustomFieldRequest
  - `label` string — The custom field name to display in the UI (free-form text).
  - `type` string — The type of data to store in the custom field.
  - `metadata` CustomFieldMetadata — Additional details about a custom field in JSON format.
    - `display_type` string — Determines how Constant Contact renders a <code>single_select</code> or <code> multi_select</code> field.
    - `allow_negative` boolean — For type <code>number</code>, determines if a value can be negative. By default, this value is false for the type <code>number</code>.
    - `decimal_places` integer — For types <code>number</code> and <code>currency</code>, determines the number of decimal places possible in the value.
    - `currency_code` string — For type <code>currency</code>, specifies the three-letter currency code to assign.
    - `integer` boolean — For types <code>number</code> and <code>currency</code>, determines whether the custom field should store only whole numbers (integers) without decimal values. If the <code>integer</code> is set to <code>false</code>, the <code>decimal_places</code> must be between 1 and 4.
    - `display_format` string — Specifies the display format for date fields in the user interface. If not specified for a date type field, defaults to <code>YYYY-MM-DD</code> format. Valid only for version 2 type dates (values are stored as actual dates to support date comparisons and validations).
  - `choices` CustomFieldChoiceRequest[] — Array of choices for custom fields of type: <code>single_select</code> or <code>multi_select</code>. Maximum number of elements for <code>checkbox</code> and <code>radio</code> display types is 20. Maximum number of elements for a <code>dropdown</code> is 100.
    - `choice_label` string — Label to display for the choice on the user interface.
    - `display_order` integer — Stores the order for displaying a list of choices.
  - `version` integer — Available if data type is <code>data</code>. Displays <code>1</code> if using legacy date fields where values are stored as strings. Displays <code>2</code> if using new date fields where values are stored as actual dates to support date comparisons and validations.

## Response `201`

New custom field successfully created

- CustomField — Custom fields details.
  - `custom_field_id` string, uuid — The system generated ID that uniquely identifies a <code>custom_field</code>.
  - `label` string, required — The custom field name to display in the UI (free-form text).
  - `name` string — The unique custom field name constructed from the label by replacing blanks with underscores.
  - `type` string, required — The data value type the custom field accepts.
  - `metadata` CustomFieldMetadata — Additional details about a custom field in JSON format.
    - `display_type` string — Determines how Constant Contact renders a <code>single_select</code> or <code> multi_select</code> field.
    - `allow_negative` boolean — For type <code>number</code>, determines if a value can be negative. By default, this value is false for the type <code>number</code>.
    - `decimal_places` integer — For types <code>number</code> and <code>currency</code>, determines the number of decimal places possible in the value.
    - `currency_code` string — For type <code>currency</code>, specifies the three-letter currency code to assign.
    - `integer` boolean — For types <code>number</code> and <code>currency</code>, determines whether the custom field should store only whole numbers (integers) without decimal values. If the <code>integer</code> is set to <code>false</code>, the <code>decimal_places</code> must be between 1 and 4.
    - `display_format` string — Specifies the display format for date fields in the user interface. If not specified for a date type field, defaults to <code>YYYY-MM-DD</code> format. Valid only for version 2 type dates (values are stored as actual dates to support date comparisons and validations).
  - `version` integer — For <code>datetime</code> data types, this is the version number associated with the custom field.
  - `choices` CustomFieldChoice[] — Choices available for <code>single_select</code> and <code>multi_select</code> type custom fields. The maximum number of elements for <code>radio</code> or <code>checkbox</code> display types is 20. Maximum number of elements for a <code>dropdown</code> is 100.
    - `custom_field_id` string, uuid — The ID that uniquely identifies a custom field.
    - `choice_id` integer — The ID that uniquely identifies the choice identifier.
    - `choice_label` string — Label to display for the choice on the user interface.
    - `display_order` integer — Stores the order for displaying a list of choices.
    - `created_at` string, date-time — Date and time that the record was created, in ISO-8601 format. System generated.
    - `updated_at` string, date-time — Date and time that the record was updated, in ISO-8601 format. System generated.
    - `deleted_at` string, date — Date the choice was deleted, in ISO-8601 format. System generated.
  - `updated_at` string, date-time — System generated date and time that the resource was updated, in ISO-8601 format.
  - `created_at` string, date-time — Date and time that the resource was created, in ISO-8601 format. System generated.

## Other responses

- `400` — Bad request. Either the JSON was malformed or there was a data validation error.
- `401` — The Access Token used is invalid.
- `403` — Forbidden request. You lack the necessary scopes, you lack the necessary user privileges, or the application is deactivated.
- `409` — Conflict. The resource you are creating or updating conflicts with an existing resource.
- `415` — Unsupported Media Type; the payload must be in JSON format, and Content-Type must be application/json.
- `500` — There was a problem with our internal service.
- `503` — Our internal service is temporarily unavailable.

---

[API](https://skmtc.net/cc/apis/appconnect-v3.md) · [All operations](https://skmtc.net/cc/apis/appconnect-v3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cc/appconnect-v3/revisions/4b4a534c818d/schema)