> 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/segments/create-a-list-segment.md).

# Create a List Segment

Create a new list segment using custom field conditions, campaign behavior filters, or both. Ideal for targeting subscribers with highly specific criteria for campaigns or automation workflows.

### ➕ Create a List Segment

Create a new segment for a subscriber list based on field conditions, campaign behavior, or a combination of both.

#### 🔹 HTTP Request

```http
POST API-URL/lists/LIST-UNIQUE-ID/segments
```

#### 🔸 URL Segments

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

#### 🔐 Authorization Header

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

***

#### 📝 POST Parameters

| Parameter | Type  | Required | Description                                                                                       |
| --------- | ----- | -------- | ------------------------------------------------------------------------------------------------- |
| `data`    | array | Yes      | List segment details including `name`, `operator_match`, `conditions`, and `campaign_conditions`. |

***

#### 📦 General Block *(Required)*

| Parameter        | Type   | Required | Description                     |
| ---------------- | ------ | -------- | ------------------------------- |
| `name`           | string | Yes      | Name of the list segment.       |
| `operator_match` | string | Yes      | Match operator: `any` or `all`. |

***

#### 📦 Conditions Block *(Optional)*

| Parameter     | Type   | Required | Description                                          |
| ------------- | ------ | -------- | ---------------------------------------------------- |
| `field_id`    | string | Yes      | ID of the custom field (use Get List Fields API).    |
| `operator_id` | string | Yes      | Condition operator ID (use condition operators API). |
| `value`       | string | Yes      | Value to compare against.                            |

***

#### 📦 Campaign Conditions Block *(Optional)*

| Parameter                  | Type    | Required | Description                                    |
| -------------------------- | ------- | -------- | ---------------------------------------------- |
| `action`                   | string  | Yes      | Action to filter by: `click` or `open`.        |
| `campaign_id`              | integer | Yes      | Campaign ID to check behavior against.         |
| `time_comparison_operator` | string  | Yes      | Time operator: `lte`, `lt`, `gte`, `gt`, `eq`. |
| `time_value`               | integer | Yes      | Time value for comparison.                     |
| `time_unit`                | string  | Yes      | Time unit: `day`, `month`, or `year`.          |

***

#### 💻 PHP Example

```php
// create a new list segment
$response = $endpoint->create('LIST-UNIQUE-ID', [
    // required
    'name'           => 'API Test List segment', // required
    'operator_match' => 'any', // required (any/all)

    // optional
    'conditions' => [
        [
            'field_id'    => '96', // required
            'operator_id' => '3',  // required (see condition operators endpoint)
            'value'       => 'example.com', // required
        ],
        [
            'field_id'    => '95',
            'operator_id' => '4',
            'value'       => 'keyword',
        ]
    ],

    'campaign_conditions' => [
        [
            'action'                   => 'click', // required (click/open)
            'campaign_id'              => '11',   // required
            'time_comparison_operator' => 'lte',   // required (lte/lt/gte/gt/eq)
            'time_value'               => '3',     // required
            'time_unit'                => 'day'    // required (day/month/year)
        ],
        [
            'action'                   => 'open',
            'campaign_id'              => '12',
            'time_comparison_operator' => 'gte',
            'time_value'               => '2',
            'time_unit'                => 'day'
        ]
    ],
]);

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

***

#### 📦 Sample JSON Response

```json
jsonCopyEdit// JSON RESPONSE
{
  "status": "success",
  "data": {
    "record": {
      "segment_uid": "mj54284tyo084",
      "segment_id": "11",
      "name": "my segment with cond updated",
      "operator_match": "any",
      "date_added": "10/23/23, 2:36 PM",
      "subscribers_count": 0,
      "conditions": [
        {
          "field_id": "96",
          "operator_id": "3",
          "value": "keyword"
        }
      ],
      "campaign_conditions": []
    }
  }
}
```

***