Describes how to view an individual custom field, and the entire collection of custom fields in a user's account.

GET a custom_field collection

Make a GET call to the /contact_custom_fields endpoint to retrieve a collection of custom fields. Use the limit parameter to limit the number of results returned on each page.

Query Parameters

This method does not currently support filtering results using the custom fields updated_at timestamp.

Example GET Collection Call

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

Endpoint Requirements

User privileges: contacts:read

Authorization scopes: contact_data

Java cURL PHP 
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.cc.email/v3/contact_custom_fields")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .build();

Response response = client.newCall(request).execute();

curl -X GET \
  'https://api.cc.email/v3/contact_custom_fields' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \

<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contact_custom_fields');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'Authorization' => 'Bearer {access_token}',
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

Response

{
    "custom_fields": [
        {
            "custom_field_id": "{custom_field_id}",
            "label": "Membership Renewal Date",
            "name": "membership_renewal_date",
            "type": "date",
            "metadata": {
                "display_format": "MM/DD/YYYY"
            },
            "version": 1,
            "created_at": "2025-04-29T14:56:16Z",
            "updated_at": "2025-05-06T16:40:52Z"
        },
        {
            "custom_field_id": "{custom_field_id}",
            "label": "maintenance contract",
            "name": "maintenance_contract",
            "type": "string",
            "updated_at": "2024-07-08T12:22:33-04:00",
            "created_at": "2024-07-08T12:22:33-04:00"
        },
        {
            "custom_field_id": "{custom_field_id}",
            "label": "Delivery preference",
            "name": "Delivery_preference",
            "type": "string",
            "updated_at": "2024-08-23T12:29:50-04:00",
            "created_at": "2024-08-23T12:29:50-04:00"
        }
    ]
}

GET a Custom Fields Details

To get details about a single custom field, make a GET call to the /contact_custom_fields/{custom_field_id} endpoint.

Example

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

Endpoint Requirements

User privileges: contacts:read

Authorization scopes: contact_data

Java cURL PHP 
OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
        .url("https://api.cc.email/v3/contact_custom_fields/{custom_field_id}")
        .method("GET", body)
        .addHeader("Accept", "*/*")
        .addHeader("Content-Type", "application/json")
        .addHeader("Authorization", "Bearer {access_token}")
        .build();
Response response = client.newCall(request).execute();

curl -X GET \
  https://api.cc.email/v3/contact_custom_fields/{custom_field_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \

<?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 => 'GET',
  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": "{custom field id}",
    "label": "subscription level checkbox",
    "name": "subscription_level_checkbox",
    "type": "single_select",
    "metadata": {
        "display_type": "checkbox"
    },
    "choices": [
        {
            "custom_field_id": "{custom field id}",
            "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": "{custom field id}",
            "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": "{custom field id}",
            "choice_id": 11733,
            "choice_label": "Bronze",
            "display_order": 4,
            "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"
}

[]:

Tags: custom_fields contacts code_samples