Create a List Field

Add a custom field to a subscriber list by specifying field type, label, tag, and optional validation or options. Useful for capturing personalized subscriber data.

➕ Create a List Field

Add a custom field to a specific subscriber list. Fields can be of various types such as text, dropdown, date, etc., and include validation options like required status, visibility, default values, and custom tags.

🔹 HTTP Request

POST API-URL/lists/LIST-UNIQUE-ID/fields

🔸 URL Segments

Segment	Required	Description
LIST-UNIQUE-ID	Yes	Unique identifier of the list.

🔐 Authorization Header

Include your customer API key:

X-API-KEY: your-api-key-here

📝 POST Parameters

Parameter	Type	Required	Description
label	string	Yes	Field label visible to users.
tag	string	Yes	Internal tag (e.g., FNAME, EMAIL, etc.). Must be unique.
required	yes/no	No	Indicates if field is required (yes or no).
help_text	string	No	Helper text shown below the field.
default_value	string	No	Pre-filled value shown in the field.
sort_order	integer	No	Order in which the field appears.
visibility	string	No	Set as visible or hidden.
type	string	Yes	Type of field (text, dropdown, date, etc.).
description	string	No	Additional notes or usage info (optional).
options	array	Conditional	Required only for dropdown, radio, checkbox field types.

---

💻 PHP Example

// create a new list field
$response = $endpoint->create('LIST-UNIQUE-ID', [
  'type'           => 'dropdown',
  'label'         => 'Text Label',
  'tag'           => 'DROPDOWN',
  'required'      => 'no',
  'visibility'    => 'visible',
  'sort_order'    => 0,
  'help_text'     => 'Help',
  'default_value' => '',
  'description'   => 'Description',
  'options'        => [
    [
      'name'  => 'Option1',
      'value' => 'Value1'
    ],
    [
      'name'  => 'Option2',
      'value' => 'Value2'
    ],
  ]
]);

// and get the response
echo '<pre>';
print_r($response->body);
echo '</pre>';

---

📦 Sample JSON Response

{
  "status": "success",
  "data": {
    "record": {
      "field_id": "111",
      "label": "Text Label",
      "tag": "DROPDOWN",
      "help_text": "Help",
      "description": "Description",
      "default_value": "",
      "required": "no",
      "visibility": "visible",
      "sort_order": "0",
      "type": {
        "name": "Dropdown",
        "identifier": "dropdown",
        "description": "Dropdown"
      },
      "list": {
        "list_uid": "lm451q7h7j3e2",
        "display_name": "My list"
      },
      "options": {
        "Value1": "Option1",
        "Value2": "Option2"
      }
    }
  }
}

---