> 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 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": []
    }
  }
}
```

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.senderwiz.com/customer/segments/create-a-list-segment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.