Create Segment

Create a new segment in your workspace. Segments are dynamic groups of contacts defined by a set of filter rules.

---

Endpoint

POST https://api.campaignlark.com/v1/segments

---

Request Body

Field	Type	Required	Description
name	string	required	Segment name. 1–64 characters.
filters	object	required	Filter configuration object.
filters.condition	string	required	Logical operator to combine filters. Must be AND or OR.
filters.filters	array	required	Array of filter objects. At least one filter is required.

---

Sample Request

POST https://api.campaignlark.com/v1/segments
Content-Type: application/json

{
  "name": "Active Subscribers",
  "filters": {
    "condition": "AND",
    "filters": [
      {
        "type": "field",
        "field_id": 1,
        "operator": "eq",
        "value": "test@example.com"
      }
    ]
  }
}

---

Filter Types

Each filter object must include a type field that determines its valid operators and value format.

field — Filter by contact field value

Filters contacts based on the value of a specific contact field.

Property	Type	Required	Description
type	string	required	Must be field.
field_id	integer	required	The ID of the field to filter on. Must exist in the workspace.
operator	string	required	Comparison operator. Valid operators depend on the field type (see below).
value	varies	required	The value to compare against.

Operators by field type:

Field Type	Valid Operators
TEXT	eq, ne, contains, not_contains, starts_with, ends_with, in, not_in
NUMBER	eq, ne, gt, lt, gte, lte
BOOLEAN	eq, ne
DATE	eq, ne, gt, lt, gte, lte
DROPDOWN_SINGLE	eq, ne, in, not_in
DROPDOWN_MULTIPLE	eq, ne, contains, not_contains
COUNTRY	eq, ne, in, not_in

Example:

{
  "type": "field",
  "field_id": 1,
  "operator": "eq",
  "value": "test@example.com"
}

---

tags — Filter by contact tags

Filters contacts based on their assigned tags.

Property	Type	Required	Description
type	string	required	Must be tags.
operator	string	required	One of eq, ne, contains, not_contains.
value	array of integers	required	Array of tag IDs. All referenced tag IDs must exist in the workspace.

Example:

{
  "type": "tags",
  "operator": "contains",
  "value": [1, 2]
}

---

open_rate — Filter by open rate

Filters contacts based on their email open rate percentage.

Property	Type	Required	Description
type	string	required	Must be open_rate.
operator	string	required	One of eq, gt, lt, gte, lte.
value	integer	required	Percentage value between 0 and 100.

Example:

{
  "type": "open_rate",
  "operator": "gte",
  "value": 50
}

---

click_rate — Filter by click rate

Filters contacts based on their email click rate percentage.

Property	Type	Required	Description
type	string	required	Must be click_rate.
operator	string	required	One of eq, gt, lt, gte, lte.
value	integer	required	Percentage value between 0 and 100.

Example:

{
  "type": "click_rate",
  "operator": "lte",
  "value": 25
}

---

last_activity — Filter by last activity date

Filters contacts based on their most recent activity. A contact matches if their last open or last click satisfies the condition.

Property	Type	Required	Description
type	string	required	Must be last_activity.
operator	string	required	One of is_after, is_before, within_last_days.
value	varies	required	Value format depends on the operator (see below).

Operators:

Operator	Value Type	Description
is_after	string (RFC 3339)	Matches contacts whose last open or click occurred after the given date.
is_before	string (RFC 3339)	Matches contacts whose last open or click occurred before the given date.
within_last_days	integer (> 0)	Matches contacts whose last open or click occurred within the last N days.

Examples:

{ "type": "last_activity", "operator": "is_after", "value": "2026-03-01T00:00:00Z" }

{ "type": "last_activity", "operator": "within_last_days", "value": 30 }

---

Response

Success — 201 Created

Asynchronously queues segment member calculation after creation.

{
  "data": {
    "id": 1,
    "name": "Active Subscribers",
    "filters": {
      "condition": "AND",
      "filters": [
        {
          "type": "field",
          "field_id": 1,
          "operator": "eq",
          "value": "test@example.com"
        }
      ]
    },
    "contact_count": 0,
    "created_at": "2026-04-09T02:20:00Z",
    "updated_at": "2026-04-09T02:20:00Z"
  }
}

---

Errors

Status	Message	Cause
400	Please provide a name for this segment	name is missing.
400	Segment name must be 64 characters or less	name exceeds 64 characters.
400	Filter condition must be AND or OR	filters.condition is missing or invalid.
400	At least one filter is required	filters.filters is empty.
400	Filter #N: Please provide a valid field_id	A field filter is missing field_id.
400	Filter #N: The specified field_id does not exist	The referenced field does not exist in the workspace.
400	Filter #N: Invalid operator for field filter. Must be one of: ...	Invalid operator for the given field type.
400	Filter #N: Tags filter value must be an array of tag IDs.	tags filter value is not a valid array of integers.
400	Filter #N: Invalid operator for tags filter. Must be one of: ...	Invalid operator for a tags filter.
400	Filter #N: Invalid operator for last activity filter. Must be one of: ...	Invalid operator for a last_activity filter.
400	Filter #N: Value must be between 0 and 100	open_rate or click_rate filter value is out of range.
400	Billing limit error	Workspace plan does not allow additional segments.