> ## Documentation Index
> Fetch the complete documentation index at: https://www.text.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Update segment definition
> Replaces the complete tree of a segment definition.
Partial tree updates are not supported. Updating a built-in definition (`0` or `1`) for the first time materializes that definition.
**Required scopes:** `customers:rw`
```json request
{
"segment_id": 1,
"definition": {
"type": "and",
"nodes": [
{
"type": "or",
"nodes": [
{
"type": "email_set"
},
{
"type": "phone_number_set"
}
]
},
{
"type": "name_set"
},
{
"type": "customer_property_set",
"customer_property_id": "9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11"
}
]
}
}
```
```json response
{
"segment_id": 1,
"segment_type": "qualified_lead",
"definition": {
"type": "and",
"nodes": [
{
"type": "or",
"nodes": [
{
"type": "email_set"
},
{
"type": "phone_number_set"
}
]
},
{
"type": "name_set"
},
{
"type": "customer_property_set",
"customer_property_id": "9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11"
}
]
},
"referenced_customer_properties_definitions_ids": [
"9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11"
],
"last_updated_at": "2026-08-08T10:25:00Z",
"agent_account_id": "bc35115a-6f12-40b4-bbb0-8187b0f68c8e",
"agent_client_id": "71d32c598862b01b9e2298281339dbc2"
}
```
```json request
{
"segment_id": 2,
"definition": {
"type": "name_set"
}
}
```
```json response
{
"segment_id": 2,
"segment_type": "custom",
"definition": {
"type": "name_set"
},
"last_updated_at": "2026-08-08T10:30:00Z",
"agent_account_id": "bc35115a-6f12-40b4-bbb0-8187b0f68c8e",
"agent_client_id": "71d32c598862b01b9e2298281339dbc2"
}
```
## OpenAPI
````yaml /api/customer-data-platform/openapi.json post /v1/update_segment_definition
openapi: 3.0.0
info:
title: Customer Data Platform API
description: A service for collecting, storing, and managing end-user data.
version: 0.0.1
servers:
- url: https://api.text.com/cdp
description: Main production server URL
security:
- PersonalAccessToken: []
- OAuth2BearerToken:
- customers:ro
paths:
/v1/update_segment_definition:
post:
tags:
- Segments
summary: Update segment definition
description: >-
Replaces the complete tree of a segment definition.
Partial tree updates are not supported. Updating a built-in definition
(`0` or `1`) for the first time materializes that definition.
operationId: updateSegmentDefinition
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSegmentDefinitionRequest'
example:
segment_id: 0
definition:
type: and
nodes:
- type: last_active_days_ago
days: 14
- type: or
nodes:
- type: email_set
- type: phone_number_set
responses:
'200':
description: The updated segment definition.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentDefinition'
example:
segment_id: 0
segment_type: lead
definition:
type: and
nodes:
- type: last_active_days_ago
days: 14
- type: or
nodes:
- type: email_set
- type: phone_number_set
last_updated_at: '2026-08-08T10:20:00Z'
agent_account_id: bc35115a-6f12-40b4-bbb0-8187b0f68c8e
agent_client_id: 71d32c598862b01b9e2298281339dbc2
'401':
description: Invalid access token
'403':
description: Insufficient scopes
'404':
description: >-
Segment definition not found (an unknown or already-deleted custom
ID; a built-in ID is materialized instead).
'422':
description: >-
Invalid request body (including a missing `segment_id`, a supplied
`segment_type`, an oversized or malformed tree, or a
`customer_property_set` node referencing a property that does not
exist or is archived).
'500':
description: Internal error
security:
- PersonalAccessToken: []
- OAuth2BearerToken:
- customers:rw
components:
schemas:
UpdateSegmentDefinitionRequest:
type: object
required:
- segment_id
- definition
additionalProperties: false
description: >-
The complete replacement for a segment definition. Partial tree updates
are not supported. The request cannot include the server-assigned
`segment_type`.
properties:
segment_id:
type: integer
format: int64
example: 0
description: >-
The definition ID. Values `0` and `1` materialize the built-in lead
and qualified lead definitions on their first update.
definition:
$ref: '#/components/schemas/SegmentDefinitionNode'
SegmentDefinition:
type: object
description: A segment definition.
required:
- segment_id
- segment_type
- definition
- last_updated_at
- agent_account_id
- agent_client_id
example:
segment_id: 2
segment_type: custom
definition:
type: and
nodes:
- type: name_set
- type: customer_property_set
customer_property_id: 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
referenced_customer_properties_definitions_ids:
- 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
last_updated_at: '2026-08-08T10:15:00Z'
agent_account_id: bc35115a-6f12-40b4-bbb0-8187b0f68c8e
agent_client_id: 71d32c598862b01b9e2298281339dbc2
properties:
segment_id:
type: integer
format: int64
description: >-
The definition ID, unique within the organization. The built-in
definitions use `0` (lead) and `1` (qualified lead). Custom
definitions receive IDs starting at `2`.
example: 2
segment_type:
type: string
enum:
- lead
- qualified_lead
- custom
description: >-
The server-assigned segment type. It cannot be set or changed
through the API.
- `lead` — the built-in definition with ID `0`.
- `qualified_lead` — the built-in definition with ID `1`.
- `custom` — a definition created through
`create_segment_definition`.
definition:
$ref: '#/components/schemas/SegmentDefinitionNode'
referenced_customer_properties_definitions_ids:
type: array
items:
type: string
format: uuid
description: >-
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
archived or deleted after the segment definition was saved.
last_updated_at:
type: string
format: date-time
nullable: true
description: >-
The date and time when the definition was most recently created or
updated. This value records request-handling time, not commit order,
and is not a concurrency token. Returns `null` for a built-in
definition before its first update.
agent_account_id:
type: string
nullable: true
description: >-
The account ID of the agent who last created or updated the
definition. Returns `null` for a built-in definition before its
first update.
agent_client_id:
type: string
nullable: true
description: >-
The client ID of the app that last created or updated the
definition. Returns `null` for a built-in definition before its
first update.
SegmentDefinitionNode:
description: >-
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.
oneOf:
- $ref: '#/components/schemas/AndSegmentNode'
- $ref: '#/components/schemas/OrSegmentNode'
- $ref: '#/components/schemas/NameSetSegmentNode'
- $ref: '#/components/schemas/EmailSetSegmentNode'
- $ref: '#/components/schemas/PhoneNumberSetSegmentNode'
- $ref: '#/components/schemas/CustomerPropertySetSegmentNode'
- $ref: '#/components/schemas/LastActiveDaysAgoSegmentNode'
discriminator:
propertyName: type
mapping:
and:
$ref: '#/components/schemas/AndSegmentNode'
or:
$ref: '#/components/schemas/OrSegmentNode'
name_set:
$ref: '#/components/schemas/NameSetSegmentNode'
email_set:
$ref: '#/components/schemas/EmailSetSegmentNode'
phone_number_set:
$ref: '#/components/schemas/PhoneNumberSetSegmentNode'
customer_property_set:
$ref: '#/components/schemas/CustomerPropertySetSegmentNode'
last_active_days_ago:
$ref: '#/components/schemas/LastActiveDaysAgoSegmentNode'
AndSegmentNode:
type: object
additionalProperties: false
required:
- type
- nodes
description: >-
An operator that evaluates to `true` when every child node evaluates to
`true`.
properties:
type:
type: string
enum:
- and
nodes:
type: array
minItems: 1
items:
$ref: '#/components/schemas/SegmentDefinitionNode'
description: The child nodes.
OrSegmentNode:
type: object
additionalProperties: false
required:
- type
- nodes
description: >-
An operator that evaluates to `true` when at least one child node
evaluates to `true`.
properties:
type:
type: string
enum:
- or
nodes:
type: array
minItems: 1
items:
$ref: '#/components/schemas/SegmentDefinitionNode'
description: The child nodes.
NameSetSegmentNode:
type: object
additionalProperties: false
required:
- type
description: >-
A condition that evaluates to `true` when the customer has a nonempty,
non-system-generated name.
properties:
type:
type: string
enum:
- name_set
EmailSetSegmentNode:
type: object
additionalProperties: false
required:
- type
description: >-
A condition that evaluates to `true` when the customer has a nonempty
email address.
properties:
type:
type: string
enum:
- email_set
PhoneNumberSetSegmentNode:
type: object
additionalProperties: false
required:
- type
description: >-
A condition that evaluates to `true` when the customer has a nonempty
phone number.
properties:
type:
type: string
enum:
- phone_number_set
CustomerPropertySetSegmentNode:
type: object
additionalProperties: false
required:
- type
- customer_property_id
description: >-
A condition that evaluates to `true` when the referenced customer
property has a non-null value for the customer. An empty but non-null
value counts as set.
properties:
type:
type: string
enum:
- customer_property_set
customer_property_id:
type: string
format: uuid
description: >-
The customer property definition ID. The API validates the UUID and
confirms that it identifies an active property when the segment
definition is created or updated. A stored segment definition
remains valid if the property is archived or deleted later.
LastActiveDaysAgoSegmentNode:
type: object
additionalProperties: false
required:
- type
- days
description: >-
A condition that evaluates to `true` when the customer's last activity
was at most the specified number of days ago.
properties:
type:
type: string
enum:
- last_active_days_ago
days:
type: integer
minimum: 1
maximum: 365
description: >-
The inclusive number of days since the customer's last recorded
activity.
securitySchemes:
PersonalAccessToken:
description: >-
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.
type: http
scheme: basic
OAuth2BearerToken:
description: >-
This API uses OAuth2 with the implicit grant flow. Learn about
the implicit grant flow.
type: oauth2
flows:
implicit:
authorizationUrl: https://accounts.livechat.com
scopes: {}
authorizationCode:
authorizationUrl: https://accounts.livechat.com
tokenUrl: https://accounts.livechat.com/token
scopes: {}
````