Skip to main content
POST
Required scopes: customers:rw

Authorizations

​
Authorization
string
header
required

Use your account ID as the username and your personal access token (PAT) as the password, or pass a Base64-encoded value directly in the Authorization header. For more information, see the personal access tokens guide.

Body

application/json

The segment definition to create. The request cannot include segment_id; supplying it returns a validation error.

​
definition
object
required

A node in a segment definition tree: one of two operators (and, or) or one of five conditions (name_set, email_set, phone_number_set, customer_property_set, last_active_days_ago). Every node type rejects unknown fields, including fields that are valid on a different node type.

​
segment_type
enum<string>

The segment type. If omitted, the API creates a custom definition. Definitions with IDs 0 and 1 do not consume a custom slot. To change an active definition, use update_segment_definition. Values are case-sensitive.

  • custom — Creates a custom definition with the next available ID starting at 2. An organization can have up to 8 active custom definitions.
  • lead — Restores the deleted lead definition at ID 0. Every organization starts with this definition, so it must be deleted before it can be restored.
  • qualified_lead — Creates the qualified lead definition at ID 1 or restores it after deletion.
Available options:
lead,
qualified_lead,
custom
Example:

"qualified_lead"

Response

The created segment definition.

A segment definition.

​
segment_id
integer<int64>
required

The definition ID. ID 0 is reserved for the lead definition, which every organization has initially. ID 1 is reserved for the qualified lead definition, which exists only after the organization creates it. Custom definitions receive IDs starting at 2.

Example:

2

​
segment_type
enum<string>
required

The segment type is fixed for the lifetime of the definition:

  • lead — The definition with ID 0.
  • qualified_lead — The definition with ID 1.
  • custom — A definition with an ID starting at 2.
Available options:
lead,
qualified_lead,
custom
​
definition
object
required

A node in a segment definition tree: one of two operators (and, or) or one of five conditions (name_set, email_set, phone_number_set, customer_property_set, last_active_days_ago). Every node type rejects unknown fields, including fields that are valid on a different node type.

​
last_updated_at
string<date-time> | null
required

The date and time when the definition was most recently created or updated. If multiple updates are processed at the same time, their timestamps may not match the order in which the updates are saved. The value is null for the lead definition before its first update.

​
agent_account_id
string | null
required

The account ID of the agent who last created or updated the definition. The value is null for the lead definition before its first update.

​
agent_client_id
string | null
required

The client ID of the app that last created or updated the definition. The value is null for the lead definition before its first update.

​
referenced_customer_properties_definitions_ids
string<uuid>[]

The customer property definition IDs referenced in definition, deduplicated in definition order. Omitted when the tree has no customer_property_set node. The array includes IDs for properties that were archived or deleted after the segment definition was saved.