Create and Update Custom Fields

Create a new custom_field

Make a POST call to the /contact_custom_fields endpoint. Include the required label and type properties in the JSON request body.

• Specify a unique label to use (free-form text).
• Choose the type of custom field to create:
  • string (text)
  • date (date-based)
  • datetime (date and time)
  • single_select (choose one from choices)
  • currency (type of currency accepted)
  • text_area (text)
  • multi_select (allow multiple selections)
  • number (accepts a number)
  • boolean (accepts true or false)

The data type of custom field you create which determines any additional properties to include:

• choices: Array of choices for custom fields of type: single_select or multi_select. Maximum number of elements for checkbox and radio display types is 20. Maximum number of elements for a dropdown is 100.

• version: Available if data type is data. Use 1 if using legacy date fields where values are stored as strings. Use 2 if using new date fields where values are stored as actual dates to support date comparisons and validations.

• metadata: Additional details about a custom field in JSON format. Options include:

  • display_type: String. For single_select or multi_select types, determines how Constant Contact renders a single_select or multi_select field. Enums include dropdown, checkbox, and radio.

  • allow_negative: Boolean. For type number, Determines if a value can be negative. Default is false.

  • decimal_places: Integer. For types number and currency. Determines the number of decimal places possible in the value.

For all property descriptions, see Custom Fields Overview.

Example POST Call - add a new custom_field

This example creates a custom field for storing the subscription level (Gold, Silver, or Bronze) for a contact. The retailer will use this new custom field to determine the appropriate email campaign discount code to send to a contact.

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"label\": \"subscription level\",\n  \"type\": \"single_select\",\n  \"metadata\": {\n    \"display_type\": \"radio\"\n  },\n  \"version\": 1,\n  \"choices\": [\n    {\n      \"choice_label\": \"Gold\",\n      \"display_order\": 1\n    },\n    {\n      \"choice_label\": \"Silver\",\n      \"display_order\": 2       \n    },\n       {\n      \"choice_label\": \"Bronze\",\n      \"display_order\": 3       \n    }\n  ]\n}");
Request request = new Request.Builder()
        .url("https://api.cc.email/v3/contact_custom_fields")
        .method("POST", body)
        .addHeader("Accept", "*/*")
        .addHeader("Content-Type", "application/json")
        .addHeader("Authorization", "Bearer {access_token}")
        .build();
Response response = client.newCall(request).execute();

Response

{
    "custom_field_id": "7b72ad8c-1adc-11f0-9d64-013455ed9fa8",
    "label": "subscription level",
    "name": "subscription_level",
    "type": "single_select",
    "metadata": {
        "display_type": "radio"
    },
    "choices": [
        {
            "custom_field_id": "7b72ad8c-1adc-11f0-9d64-013455ed9fa8",
            "choice_id": 21249,
            "choice_label": "Gold",
            "display_order": 1,
            "created_at": "2025-04-16T16:04:03Z",
            "updated_at": "2025-04-16T16:04:03Z"
        },
        {
            "custom_field_id": "7b72ad8c-1adc-11f0-9d64-013455ed9fa8",
            "choice_id": 28784,
            "choice_label": "Silver",
            "display_order": 2,
            "created_at": "2025-04-16T16:04:03Z",
            "updated_at": "2025-04-16T16:04:03Z"
        },
        {
            "custom_field_id": "7b72ad8c-1adc-11f0-9d64-013455ed9fa8",
            "choice_id": 11733,
            "choice_label": "Bronze",
            "display_order": 3,
            "created_at": "2025-04-16T16:04:03Z",
            "updated_at": "2025-04-16T16:04:03Z"
        }
    ],
    "version": 1,
    "created_at": "2025-04-16T16:04:02Z",
    "updated_at": "2025-04-16T16:04:02Z"
}

Update a Custom Field

To update an existing custom field, make a PUT call to the /contact_custom_fields/{custom_field_id} endpoint and include the required label and type properties in the JSON request body.

For single_select and multi_select custom field data types, you can choose to update choices and metadata properties.

• To update choices for single_select and multi_select custom field data types, you must include the following required properties in the request body:

  • choice_id
  • choice_label
  • display_order

• To update metadata, include the properties for the metadata type you want to update in the request body.

For property descriptions, see Custom Fields Overview.

Example PUT Call

This example changes an existing custom field metadata display_type from radio to checkbox.

OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"label\": \"subscription level checkbox\",\n  \"type\": \"single_select\",\n  \"metadata\": {\n    \"display_type\": \"checkbox\"\n  }\n}");
Request request = new Request.Builder()
        .url("https://api.cc.email/v3/contact_custom_fields/{custom_field_id}")
        .method("PUT", body)
        .addHeader("Accept", "*/*")
        .addHeader("Content-Type", "application/json")
        .addHeader("Authorization", "Bearer {access_token})
        .build();
Response response = client.newCall(request).execute();

Response

{
    "custom_field_id": "6a72ad8c-1adc-11f0-9d64-013455ed9fa8",
    "label": "subscription level checkbox",
    "name": "subscription_level_checkbox",
    "type": "single_select",
    "metadata": {
        "display_type": "checkbox"
    },
    "choices": [
        {
            "custom_field_id": "6a72ad8c-1adc-11f0-9d64-013455ed9fa8",
            "choice_id": 21249,
            "choice_label": "Gold",
            "display_order": 1,
            "created_at": "2025-04-16T16:04:03Z",
            "updated_at": "2025-04-16T16:04:03Z"
        },
        {
            "custom_field_id": "6a72ad8c-1adc-11f0-9d64-013455ed9fa8",
            "choice_id": 28784,
            "choice_label": "Silver",
            "display_order": 2,
            "created_at": "2025-04-16T16:04:03Z",
            "updated_at": "2025-04-16T16:04:03Z"
        },
        {
            "custom_field_id": "6a72ad8c-1adc-11f0-9d64-013455ed9fa8",
            "choice_id": 11733,
            "choice_label": "Bronze",
            "display_order": 3,
            "created_at": "2025-04-16T16:04:03Z",
            "updated_at": "2025-05-02T19:53:16Z"
        }
    ],
    "version": 1,
    "created_at": "2025-04-16T16:04:02Z",
    "updated_at": "2025-05-06T18:01:15Z"
}