Describes how to create a new custom field, and to update an existing custom field.

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]{custom_fields.html}.

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.

POST https://api.cc.email/v3/contact_custom_fields

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

Java cURL PHP 
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();


curl --location 'https://api.cc.email/v3/contact_custom_fields' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "label": "subscription level",
  "type": "single_select",
  "metadata": {
    "display_type": "radio"
  },
  "version": 1,
  "choices": [
    {
      "choice_label": "Gold",
      "display_order": 1
    },
    {
      "choice_label": "Silver",
      "display_order": 2       
    },
       {
      "choice_label": "Bronze",
      "display_order": 3       
    }
  ]
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cc.email/v3/contact_custom_fields',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "label": "subscription level",
  "type": "single_select",
  "metadata": {
    "display_type": "radio"
  },
  "version": 1,
  "choices": [
    {
      "choice_label": "Gold",
      "display_order": 1
    },
    {
      "choice_label": "Silver",
      "display_order": 2       
    },
       {
      "choice_label": "Bronze",
      "display_order": 3       
    }
  ]
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: */*',
    'Content-Type: application/json',
    'Authorization: Bearer {access_token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

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"
}

Try it!

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]{custom_fields.html}.

Example PUT Call

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

PUT https://api.cc.email/v3/contact_custom_fields/{custom_field_id}

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

Java cURL PHP 
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();

curl --location --request PUT 'https://api.cc.email/v3/contact_custom_fields/{custom_field_id}' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "label": "subscription level checkbox",
  "type": "single_select",
  "metadata": {
    "display_type": "checkbox"
  }
}'


<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cc.email/v3/contact_custom_fields/{custom_field_id}',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'PUT',
  CURLOPT_POSTFIELDS =>'{
  "label": "subscription level checkbox",
  "type": "single_select",
  "metadata": {
    "display_type": "checkbox"
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Accept: */*',
    'Content-Type: application/json',
    'Authorization: Bearer {access_token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

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"
}

Try it!

[]:

Tags: custom_fields contacts code_samples