> For the complete documentation index, see [llms.txt](https://api.senderwiz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.senderwiz.com/customer/fields/create-a-list-field.md).

# 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

```http
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

```php
// 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

```json
{
  "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"
      }
    }
  }
}
```

***