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

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

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

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

---