---
openapi: 3.0.0
info:
  title: Customer Data Platform API
  description:
    Customer Data Platform API is a service for collecting, storing, and
    managing end-user data.
  version: 0.0.1
servers:
  - url: https://api.text.com/cdp
paths:
  "/get_customer":
    post:
      summary: Get customer
      description: "Returns the customer data. Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  format: uuid
                  description: The requested customer ID.
      responses:
        "200":
          description: Customer data.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Customer"
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description: Customer not found
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/get_merged_customer":
    post:
      summary: Get merged customer
      description: "Returns the merged customer data. Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  format: uuid
                  description: The requested customer ID.
      responses:
        "200":
          description: Merged customer data.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Customer"
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description: Customer not found
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/get_merged_customer_chats":
    post:
      summary: Get merged customer chat IDs
      description: "Returns the merged customer chat IDs. Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
              properties:
                customer_id:
                  type: string
                  format: uuid
                  description: The requested customer ID.
      responses:
        "200":
          description: Array of chat IDs for the merged customer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  chat_ids:
                    type: array
                    items:
                      type: string
                      format: uuid
                      description: The requested customer chat IDs.
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description: Customer not found
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/get_merged_customer_tickets":
    post:
      summary: Get merged customer ticket IDs
      description: "Returns the merged customer ticket IDs. Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - customer_id
              properties:
                customer_id:
                  type: string
                  format: uuid
                  description: The requested customer ID.
                silo:
                  type: string
                  enum:
                    - inbox
                    - archive
                    - spam
                    - trash
                  description: An optional ticket silo filter.
      responses:
        "200":
          description: Array of ticket IDs for the merged customer.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket_ids:
                    type: array
                    items:
                      type: string
                      format: uuid
                      description: The requested customer ticket IDs.
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description: Customer not found
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/v1/list_customers":
    post:
      summary: v1/List customers
      description:
        "Available for Text App only. Search and list customers with filtering,
        sorting, and pagination. Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/ListCustomersRequest"
            examples:
              simple_search:
                summary: Simple free-text search
                value:
                  query: john
                  results_per_page: 50
              advanced_filters:
                summary: Advanced filtering with multiple criteria
                value:
                  query: john
                  filters:
                    - operator: AND
                      clauses:
                        - field: name
                          operator: contains
                          values:
                            - john
                            - jane
                        - field: country
                          operator: is
                          values:
                            - Poland
                            - Latvia
                          negate: true
                        - field: last_activity
                          operator: range
                          range:
                            from: "2025-01-01T00:00:00Z"
                            to: "2025-03-01T00:00:00Z"
                        - field: threads_count
                          operator: range
                          range:
                            from: 50
                            to: 100
                        - field: tickets_count
                          operator: is
                          values:
                            - 10
                  results_per_page: 50
                  sort:
                    last_activity: desc
                    9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11: asc
              filter_groups_example:
                summary: Multiple filter groups with OR logic
                value:
                  filters:
                    - operator: AND
                      clauses:
                        - field: email
                          operator: is
                          values:
                            - user@example.com
                        - field: threads_count
                          operator: range
                          range:
                            from: 10
                            to: 100
                    - operator: OR
                      clauses:
                        - field: name
                          operator: exists
                        - field: phone_number
                          operator: starts_with
                          values:
                            - "+48"
                            - "+121"
                  results_per_page: 25
              cart_filters:
                summary: Filter by cart value and last updated date
                value:
                  filters:
                    - operator: AND
                      clauses:
                        - field: cart_total_usd
                          operator: range
                          range:
                            from: 100
                            to: 500
                        - field: cart_last_updated_at
                          operator: range
                          range:
                            from: "2025-01-01T00:00:00Z"
                            to: "2025-03-01T00:00:00Z"
                  results_per_page: 50
              segment_membership:
                summary: Customers in segment 5
                value:
                  filters:
                    - operator: AND
                      clauses:
                        - field: segment_id
                          operator: is
                          values:
                            - 5
              any_segment_membership:
                summary: Customers in segment 5 or 7
                value:
                  filters:
                    - operator: AND
                      clauses:
                        - field: segment_id
                          operator: is
                          values:
                            - 5
                            - 7
              all_segment_memberships:
                summary: Customers in both segment 5 and segment 7
                value:
                  filters:
                    - operator: AND
                      clauses:
                        - field: segment_id
                          operator: is
                          values:
                            - 5
                        - field: segment_id
                          operator: is
                          values:
                            - 7
              neither_segment_membership:
                summary: Customers in neither segment 5 nor segment 7
                value:
                  filters:
                    - operator: AND
                      clauses:
                        - field: segment_id
                          operator: is
                          values:
                            - 5
                            - 7
                          negate: true
              segment_membership_entered_at:
                summary: Customers who joined segment 5 on or after 1 August 2026
                value:
                  filters:
                    - operator: AND
                      clauses:
                        - field: segment_id
                          operator: is
                          values:
                            - 5
                          entered_at:
                            from: "2026-08-01T00:00:00Z"
              any_segment_membership_entered_at:
                summary: Customers who joined any segment within a date range
                value:
                  filters:
                    - operator: AND
                      clauses:
                        - field: segment_id
                          operator: is
                          entered_at:
                            from: "2026-07-30T00:00:00Z"
                            to: "2026-08-06T00:00:00Z"
      responses:
        "200":
          description: A list of customers matching search criteria.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ListCustomersResponse"
              example:
                customers:
                  - customer_id: cf89fa3a-5ee9-4bdb-84ec-38824b2e2786
                    organization_id: b7eff798-f8df-4364-8052-649c35c9ed0c
                    product: livechat
                    monitoring:
                    custom_fields:
                    statistics:
                next_page_id: "2"
                total: 1523
                page_id: "1"
        "400":
          description: Invalid request (validation error)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example:
                      "validation error: invalid field 'city'. Allowed fields:
                      address_city, address_country, ... and customer_property"
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/v1/get_customers_count":
    post:
      summary: v1/Get customers count
      description:
        "Available for Text App only. Returns a count of customers matching
        the specified search criteria. The request body follows the same structure
        as `v1/list_customers`, but sorting and pagination parameters are ignored.
        Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/GetCustomersCountRequest"
      responses:
        "200":
          description: The count of customers matching search criteria.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    format: int64
                    example: 1523
        "400":
          description: Invalid request (validation error)
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/v1/create_customer_property_definition":
    post:
      summary: v1/Create customer property definition
      description:
        "Creates a new customer property schema entry for the caller's
        organization. The property `id` is a UUID generated by the store. The maximum
        number of customer properties an organization can have depends on its plan.
        Required scope: `customers:rw`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateCustomerPropertyRequest"
            examples:
              number_property:
                summary: Numeric property
                value:
                  name: lifetime_value
                  type: number
                  description: Lifetime spend in USD
              timestamp_property:
                summary: Timestamp property with a format
                value:
                  name: signed_up_at
                  type: timestamp
                  type_configuration:
                    format: date-time
      responses:
        "200":
          description: The created customer property.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CustomerProperty"
              examples:
                number_property:
                  summary: Numeric property (no type_configuration)
                  value:
                    id: 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
                    name: lifetime_value
                    type: number
                    type_configuration: {}
                    description: Lifetime spend in USD
                    has_value: false
                timestamp_property:
                  summary: Timestamp property with a format
                  value:
                    id: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                    name: signed_up_at
                    type: timestamp
                    type_configuration:
                      format: date-time
                    has_value: false
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "409":
          description: A property with the same name already exists in the organization.
        "422":
          description:
            Invalid request body, the organization's plan-driven customer
            properties limit has been reached, or the resulting schema exceeds the
            upstream size limit.
        "500":
          description: Internal error
  "/v1/update_customer_property_definition":
    post:
      summary: v1/Update customer property definition
      description:
        "Updates the editable fields of an existing customer property.
        Only `name`, `description` and `type_configuration.allowed_values` can be
        changed; `type` and `type_configuration.format` are immutable. Requests that
        include immutable or unknown fields are rejected with a validation error.
        At least one of `name`, `description`, `type_configuration` must be provided.
        Required scope: `customers:rw`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateCustomerPropertyRequest"
            examples:
              renamed:
                summary: Rename a numeric property
                value:
                  id: 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
                  name: ltv_usd
                  description: Lifetime value (USD)
              timestamp_property:
                summary: Update a timestamp property's allowed values
                value:
                  id: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                  type_configuration:
                    allowed_values:
                      - "2026-01-01T00:00:00Z"
      responses:
        "200":
          description: The updated customer property.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CustomerProperty"
              examples:
                renamed:
                  summary: Renamed numeric property
                  value:
                    id: 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
                    name: ltv_usd
                    type: number
                    type_configuration: {}
                    description: Lifetime value (USD)
                    has_value: true
                timestamp_property:
                  summary: Timestamp property after updating its allowed values
                  value:
                    id: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                    name: signed_up_at
                    type: timestamp
                    type_configuration:
                      format: date-time
                      allowed_values:
                        - "2026-01-01T00:00:00Z"
                    has_value: false
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description: Customer property not found
        "409":
          description:
            Another property in the organization already uses the requested
            name.
        "422":
          description:
            Invalid request body (including attempts to set immutable `type`
            or `type_configuration.format` fields), or the resulting schema exceeds
            the upstream size limit.
        "500":
          description: Internal error
  "/v1/delete_customer_property_definition":
    post:
      summary: v1/Delete customer property definition
      description:
        "Deletes a customer property definition. It will no longer be returned
        by any definition-listing response. Required scope: `customers:rw`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DeleteCustomerPropertyRequest"
            examples:
              delete:
                summary: Remove a property
                value:
                  id: 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
      responses:
        "200":
          description: The property was deleted.
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description: Customer property not found
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/v1/get_customer_properties_definitions":
    post:
      summary: v1/List customer property definitions
      description:
        "Returns all customer property schema entries for the caller's
        organization, plus the schema-level `last_updated_at` timestamp and `last_updated_by`
        account ID of the most recent mutation. Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: List of customer properties in the organization.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ListCustomerPropertiesResponse"
              example:
                last_updated_at: "2026-01-15T09:30:00Z"
                last_updated_by: 3ac8f2b1-1f6c-4a2b-8d0e-9b6f1f6c8a2b
                properties:
                  - id: 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
                    name: lifetime_value
                    type: number
                    type_configuration: {}
                    description: Lifetime spend in USD
                    has_value: true
                  - id: a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d
                    name: signed_up_at
                    type: timestamp
                    type_configuration:
                      format: date-time
                    has_value: false
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/v1/set_customer_properties_values":
    post:
      summary: v1/Set customer properties values
      description:
        "Sets one or more customer properties' values for the specified
        customer. Each property is validated against its definition (type and type
        configuration). Setting a property value to `null` clears it. Unknown fields
        in the request body are rejected. Required scope: `customers:rw`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SetCustomerPropertiesValuesRequest"
            examples:
              set_multiple_properties:
                summary: Set multiple properties values
                value:
                  customer_id: cf89fa3a-5ee9-4bdb-84ec-38824b2e2786
                  properties:
                    9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11: 42
                    a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d: hello
              clear_property:
                summary: Clear the property value
                value:
                  customer_id: cf89fa3a-5ee9-4bdb-84ec-38824b2e2786
                  properties:
                    9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11:
      responses:
        "200":
          description: Properties have been set successfully.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/EmptyResponse"
              example: {}
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "422":
          description:
            Invalid request body (e.g. missing or empty `customer_id`,
            empty `properties` map, more than 100 entries, unknown property ID, or
            a value that does not match the property type).
        "500":
          description: Internal error
  "/v1/update_customer":
    post:
      summary: v1/Update customer
      description: |
        Updates native CDP fields for the specified customer.

        | Field | Supported values |
        |---|---|
        | `relationship_level` | `vip` to assign the level, `null` to remove it |

        Required scope: `customers:rw`.
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateCustomerRequest"
            examples:
              assign_vip:
                summary: Assign VIP
                value:
                  customer_id: cf89fa3a-5ee9-4bdb-84ec-38824b2e2786
                  relationship_level: vip
              remove_relationship_level:
                summary: Remove the relationship level
                value:
                  customer_id: cf89fa3a-5ee9-4bdb-84ec-38824b2e2786
                  relationship_level:
      responses:
        "200":
          description: Customer has been updated successfully.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/EmptyResponse"
              example: {}
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description: Customer not found
        "422":
          description:
            Invalid request body, missing `customer_id` or `relationship_level`,
            or unsupported relationship level.
        "500":
          description: Internal error
  "/v1/has_sales_events":
    post:
      summary: v1/Has sales events
      description:
        "Returns whether the organization has recorded any sales activity,
        optionally scoped to a single store. Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                store_uuid:
                  type: string
                  format: uuid
                  description:
                    Optional store UUID. When provided the check is scoped
                    to that store; when omitted it covers the whole organization.
      responses:
        "200":
          description: Whether the organization (or store) has any sales events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  has_sales_events:
                    type: boolean
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "422":
          description: Invalid request body (e.g. malformed `store_uuid`).
        "500":
          description: Internal error
  "/v1/get_segment_definitions":
    post:
      summary: v1/Get segment definitions
      description:
        "Returns every active segment definition for the caller's organization,
        including the two built-in definitions — lead (`0`) and qualified lead (`1`)
        — even before they have been edited. A built-in definition that has been deleted
        is absent until it is restored with `create_segment_definition`, so the array
        can be empty. Definitions are ordered by `segment_id`. Required scope: `customers:ro`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: List of segment definitions in the organization.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/GetSegmentDefinitionsResponse"
              example:
                segment_definitions:
                  - segment_id: 0
                    segment_type: lead
                    definition:
                      type: or
                      nodes:
                        - type: email_set
                        - type: phone_number_set
                    last_updated_at:
                    agent_account_id:
                    agent_client_id:
                  - segment_id: 1
                    segment_type: qualified_lead
                    definition:
                      type: and
                      nodes:
                        - type: or
                          nodes:
                            - type: email_set
                            - type: phone_number_set
                        - type: name_set
                    last_updated_at:
                    agent_account_id:
                    agent_client_id:
                  - 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
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "422":
          description: Invalid request body
        "500":
          description: Internal error
  "/v1/create_segment_definition":
    post:
      summary: v1/Create segment definition
      description:
        "Creates a new custom segment definition, or restores a deleted
        built-in one. Without `segment_type`, or with `custom`, the ID is allocated
        by the store, not the caller, and is always `2` or higher because `0` and
        `1` belong to the built-in definitions; at most 8 custom definitions can be
        active per organization at once. With `segment_type` `lead` or `qualified_lead`,
        the call restores that built-in definition at its fixed ID (`0` or `1`) with
        the supplied `definition` tree, and consumes no custom slot. The built-in
        must be deleted first — restoring an active one is a validation error, and
        `update_segment_definition` never restores. Required scope: `customers:rw`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CreateSegmentDefinitionRequest"
            examples:
              name_and_property:
                summary: Named customers with a set customer property
                value:
                  definition:
                    type: and
                    nodes:
                      - type: name_set
                      - type: customer_property_set
                        customer_property_id: 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
              recently_active_lead:
                summary: Leads active within the last 30 days
                value:
                  definition:
                    type: and
                    nodes:
                      - type: last_active_days_ago
                        days: 30
                      - type: or
                        nodes:
                          - type: email_set
                          - type: phone_number_set
              restore_builtin_qualified_lead:
                summary: Restore the deleted built-in qualified lead definition
                value:
                  segment_type: qualified_lead
                  definition:
                    type: and
                    nodes:
                      - type: name_set
                      - type: or
                        nodes:
                          - type: email_set
                          - type: phone_number_set
      responses:
        "200":
          description: The created segment definition.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SegmentDefinition"
              examples:
                name_and_property:
                  summary: Named customers with a set customer property
                  value:
                    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
                recently_active_lead:
                  summary:
                    Leads active within the last 30 days (no referenced customer
                    properties)
                  value:
                    segment_id: 3
                    segment_type: custom
                    definition:
                      type: and
                      nodes:
                        - type: last_active_days_ago
                          days: 30
                        - type: or
                          nodes:
                            - type: email_set
                            - type: phone_number_set
                    last_updated_at: "2026-08-08T10:16:00Z"
                    agent_account_id: bc35115a-6f12-40b4-bbb0-8187b0f68c8e
                    agent_client_id: 71d32c598862b01b9e2298281339dbc2
                restore_builtin_qualified_lead:
                  summary:
                    The restored built-in qualified lead definition, at its
                    fixed ID and with the supplied tree
                  value:
                    segment_id: 1
                    segment_type: qualified_lead
                    definition:
                      type: and
                      nodes:
                        - type: name_set
                        - type: or
                          nodes:
                            - type: email_set
                            - type: phone_number_set
                    last_updated_at: "2026-08-08T10:17:00Z"
                    agent_account_id: bc35115a-6f12-40b4-bbb0-8187b0f68c8e
                    agent_client_id: 71d32c598862b01b9e2298281339dbc2
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "422":
          description:
            Invalid request body (including a supplied `segment_id`, a
            `segment_type` outside the enum, an oversized or malformed tree, or a
            `customer_property_set` node referencing a property that does not exist
            or is archived), the built-in definition named by `segment_type` is still
            active and so cannot be restored, or the organization's custom-definition
            limit (8) has been reached.
        "500":
          description: Internal error
  "/v1/update_segment_definition":
    post:
      summary: v1/Update segment definition
      description:
        "Replaces the entire tree of an existing segment definition; partial
        tree updates are not supported. `segment_id` must be provided explicitly —
        an explicit `0` or `1` updates, and on its first update materializes, the
        corresponding built-in definition. A deleted built-in definition is not found
        here; restore it with `create_segment_definition`. Required scope: `customers:rw`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/UpdateSegmentDefinitionRequest"
            examples:
              update_builtin_lead:
                summary:
                  Materialize the built-in lead definition with an activity
                  window
                value:
                  segment_id: 0
                  definition:
                    type: and
                    nodes:
                      - type: last_active_days_ago
                        days: 14
                      - type: or
                        nodes:
                          - type: email_set
                          - type: phone_number_set
              update_builtin_qualified_lead:
                summary:
                  Materialize the built-in qualified lead definition with a
                  stricter tree
                value:
                  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
              update_custom_definition:
                summary: Replace a custom definition's tree
                value:
                  segment_id: 2
                  definition:
                    type: name_set
      responses:
        "200":
          description: The updated segment definition.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SegmentDefinition"
              examples:
                update_builtin_lead:
                  summary: The materialized built-in lead definition
                  value:
                    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
                update_builtin_qualified_lead:
                  summary: The materialized built-in qualified lead definition
                  value:
                    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
                update_custom_definition:
                  summary: The custom definition with its replaced tree
                  value:
                    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
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description:
            Segment definition not found (an unknown or already-deleted
            custom ID, or a deleted built-in ID — restore it with `create_segment_definition`).
            A built-in ID that has never been edited 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
  "/v1/delete_segment_definition":
    post:
      summary: v1/Delete segment definition
      description:
        "Soft-deletes a segment definition, custom or built-in. The deleted
        definition stops being evaluated and is absent from `get_segment_definitions`,
        which can leave the organization with no definitions at all. Existing customer
        memberships for it are preserved. A custom ID is never reused; a built-in
        one (`0` or `1`) can be brought back with `create_segment_definition`. Required
        scope: `customers:rw`."
      parameters:
        - "$ref": "#/components/parameters/AuthHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/DeleteSegmentDefinitionRequest"
            examples:
              delete:
                summary: Delete a custom definition
                value:
                  segment_id: 2
              delete_builtin:
                summary: Delete the built-in lead definition
                value:
                  segment_id: 0
      responses:
        "200":
          description: The definition was deleted.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
              example: {}
        "401":
          description: Invalid access token
        "403":
          description: Insufficient scopes
        "404":
          description:
            Segment definition not found (an unknown or already-deleted
            custom ID, or an already-deleted built-in ID).
        "422":
          description: Invalid request body (e.g. a missing `segment_id`).
        "500":
          description: Internal error
components:
  parameters:
    AuthHeader:
      name: Authorization
      in: header
      required: true
      schema:
        type: string
      description:
        A valid access token, either an OAuth2 Token (Bearer) or a Personal
        Access Token (Basic).
  schemas:
    EmptyResponse:
      type: object
      description: An empty JSON object. The call carries no data back.
      additionalProperties: false
    Customer:
      type: object
      required:
        - customer_id
        - organization_id
        - product
        - monitoring
        - custom_fields
        - statistics
      properties:
        customer_id:
          type: string
          format: uuid
        organization_id:
          type: string
          format: uuid
        product:
          type: string
          example: livechat
        monitoring:
          oneOf:
            - "$ref": "#/components/schemas/Monitoring"
            - type: "null"
        custom_fields:
          oneOf:
            - "$ref": "#/components/schemas/CustomFields"
            - type: "null"
        statistics:
          oneOf:
            - "$ref": "#/components/schemas/Statistics"
            - type: "null"
        chat:
          "$ref": "#/components/schemas/Chat"
        invitation:
          "$ref": "#/components/schemas/Invitation"
        customer_properties:
          type: object
          additionalProperties:
            "$ref": "#/components/schemas/CustomerPropertyValue"
          description:
            A map of customer property definition IDs to their current
            values. Omitted when the customer has no property values set.
        tickets:
          type: object
          additionalProperties:
            "$ref": "#/components/schemas/Ticket"
        omnichannel:
          "$ref": "#/components/schemas/Omnichannel"
        orders:
          type: array
          items:
            "$ref": "#/components/schemas/Order"
        carts:
          type: array
          items:
            "$ref": "#/components/schemas/Cart"
        segment_memberships:
          type: array
          items:
            "$ref": "#/components/schemas/SegmentMembership"
          description:
            The customer's per-segment membership state. Contains one entry
            for each segment that has been evaluated for the customer.
        relationship_level:
          type: string
          enum:
            - vip
          nullable: true
          description: Relationship level. Omitted when no relationship level is assigned.
        opt_ins:
          type: object
          additionalProperties:
            type: array
            items:
              "$ref": "#/components/schemas/OptIn"
          description:
            Marketing consents the customer has granted, keyed by channel
            (`sms`, `whatsapp`, `messenger`, `instagram`). Only consents valid at
            the time of the request are returned; a channel left with none is omitted,
            as is the whole field when the customer has no consents.
    OptIn:
      type: object
      required:
        - asset_id
      properties:
        asset_id:
          type: string
          description:
            The address the consent covers - a phone number in E.164 for
            telephony channels, a handle for the others.
          example: "+48555111222"
        valid_until:
          type: string
          format: date-time
          description: When the consent expires. Omitted when it does not expire.
          example: "2026-09-01T00:00:00Z"
    Monitoring:
      type: object
      required:
        - name
        - name_is_default
        - email
        - suggested_email
        - avatar_url
        - phone_number
        - session_fields
        - visits
        - version
        - state
        - online
        - current_group_ids
        - created_at
        - master_id
      properties:
        name:
          type: string
        name_is_default:
          type: boolean
        email:
          type: string
        suggested_email:
          type: string
          description: An email captured for the customer without their confirmation.
        avatar_url:
          type: string
        phone_number:
          type: string
        session_fields:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
        visits:
          type: array
          items:
            "$ref": "#/components/schemas/Visit"
        version:
          type: integer
        state:
          "$ref": "#/components/schemas/MonitoringState"
        online:
          type: boolean
        current_group_ids:
          type: array
          items:
            type: integer
        created_at:
          type: string
          format: date-time
        master_id:
          type: string
          format: uuid
        address:
          "$ref": "#/components/schemas/Address"
    Address:
      type: object
      properties:
        address:
          type: string
        city:
          type: string
        country:
          type: string
        state:
          type: string
        postal_code:
          type: string
    MonitoringState:
      type: string
      enum:
        - ""
        - browsing
        - queued
        - invited
        - chatting
        - chat closed
        - offline
    Visit:
      type: object
      required:
        - id
        - started_at
        - geolocation
      properties:
        id:
          type: integer
        started_at:
          type: string
        ended_at:
          type: string
        geolocation:
          "$ref": "#/components/schemas/Geolocation"
        ip:
          type: string
        user_agent:
          type: string
        page_referrer:
          type: string
        first_visited_page:
          "$ref": "#/components/schemas/Page"
        pages:
          type: array
          items:
            "$ref": "#/components/schemas/Page"
    Page:
      type: object
      required:
        - id
        - started_at
        - url
        - title
        - group_ids
      properties:
        id:
          type: integer
        started_at:
          type: string
        url:
          type: string
        title:
          type: string
        group_ids:
          type: array
          items:
            type: integer
    Geolocation:
      type: object
      required:
        - latitude
        - longitude
        - country
        - country_code
        - region
        - city
        - timezone
      properties:
        latitude:
          type: string
        longitude:
          type: string
        country:
          type: string
        country_code:
          type: string
        region:
          type: string
        city:
          type: string
        timezone:
          type: string
    CustomFields:
      type: object
      additionalProperties:
        type: object
        additionalProperties:
          type: string
      example:
        58737b5829e65621a45d598aa6f2ed8e:
          phone: 0300 222 0000
          address: Prime Minister's Office, 10 Downing Street
    Statistics:
      type: object
      required:
        - chats_count
        - threads_count
        - visits_count
        - page_views_count
        - greetings_accepted_count
        - greetings_converted_count
        - tickets_count
        - tickets_inbox_count
        - tickets_archive_count
        - tickets_spam_count
        - tickets_trash_count
        - orders_count
      properties:
        chats_count:
          type: integer
        threads_count:
          type: integer
        visits_count:
          type: integer
        page_views_count:
          type: integer
        greetings_accepted_count:
          type: integer
        greetings_converted_count:
          type: integer
        tickets_count:
          type: integer
        tickets_inbox_count:
          type: integer
        tickets_archive_count:
          type: integer
        tickets_spam_count:
          type: integer
        tickets_trash_count:
          type: integer
        orders_count:
          type: integer
        last_activity_at:
          type: string
          format: date-time
        last_visit_at:
          type: string
          format: date-time
        last_ticket_created_at:
          type: string
          format: date-time
        last_ticket_customer_message_at:
          type: string
          format: date-time
        last_chat_at:
          type: string
          format: date-time
        last_omnichannel_chat_at:
          type: string
          format: date-time
        last_campaign_interaction_at:
          type: string
          format: date-time
    Chat:
      type: object
      required:
        - active
        - chat_id
        - thread_id
        - last_updated_at
        - group_ids
      properties:
        active:
          type: boolean
        chat_id:
          type: string
        thread_id:
          format: string
        last_updated_at:
          type: string
          format: date-time
        group_ids:
          type: array
          items:
            type: integer
        source_customer_client_id:
          type: string
    Invitation:
      type: object
      required:
        - active
        - greeting_id
        - greeting_unique_id
        - greeting_name
      properties:
        active:
          type: boolean
        greeting_id:
          type: integer
        greeting_unique_id:
          format: uuid
        greeting_name:
          type: string
    Ticket:
      type: object
      required:
        - ticket_id
        - hd_license_id
        - status
        - created_at
        - last_updated_at
      properties:
        ticket_id:
          type: string
          format: uuid
        hd_license_id:
          type: string
        status:
          type: string
        silo:
          "$ref": "#/components/schemas/TicketSilo"
        created_at:
          type: string
          format: date-time
        last_updated_at:
          type: string
          format: date-time
        last_customer_message_at:
          type: string
          format: date-time
    TicketSilo:
      type: string
      enum:
        - inbox
        - archive
        - spam
        - trash
    Omnichannel:
      type: object
      properties:
        fbmessenger:
          type: array
          items:
            "$ref": "#/components/schemas/OmnichannelFBMessenger"
        twilio:
          type: array
          items:
            "$ref": "#/components/schemas/OmnichannelTwilio"
        whatsapp:
          type: array
          items:
            "$ref": "#/components/schemas/OmnichannelWhatsApp"
        instagram:
          type: array
          items:
            "$ref": "#/components/schemas/OmnichannelInstagram"
        telegram:
          type: array
          items:
            "$ref": "#/components/schemas/OmnichannelTelegram"
        sms:
          type: array
          items:
            "$ref": "#/components/schemas/OmnichannelSms"
    OmnichannelFBMessenger:
      type: object
      required:
        - id
        - is_verified_user
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        profile_pic:
          type: string
          format: url
        gender:
          type: string
        locale:
          type: string
        is_verified_user:
          type: boolean
    OmnichannelTwilio:
      type: object
      required:
        - phone_number
      properties:
        phone_number:
          type: string
    OmnichannelWhatsApp:
      type: object
      required:
        - id
        - phone_number
      properties:
        id:
          type: string
        name:
          type: string
        phone_number:
          type: string
    OmnichannelInstagram:
      type: object
      required:
        - ig_user_id
      properties:
        ig_user_id:
          type: string
        username:
          type: string
        name:
          type: string
        profile_pic:
          type: string
          format: url
        follower_count:
          type: integer
          format: int64
        is_verified_user:
          type: boolean
        is_user_follow_business:
          type: boolean
        is_business_follow_user:
          type: boolean
    OmnichannelTelegram:
      type: object
      required:
        - telegram_user_id
      properties:
        telegram_user_id:
          type: integer
          format: int64
        first_name:
          type: string
        last_name:
          type: string
        username:
          type: string
        language_code:
          type: string
        display_name:
          type: string
        is_premium:
          type: boolean
          nullable: true
    OmnichannelSms:
      type: object
      required:
        - phone_number
      properties:
        phone_number:
          type: string
    Order:
      type: object
      required:
        - customer_id
        - store_platform
        - store_uuid
        - order_id
        - order_number
        - currency
        - total_price
        - created_at
        - event_id
        - event_client_id
      properties:
        customer_id:
          type: string
          format: uuid
        store_platform:
          type: string
        store_uuid:
          type: string
          format: uuid
        order_id:
          type: string
        order_number:
          type: string
        currency:
          type: string
        total_price:
          type: number
          format: double
        created_at:
          type: string
          format: date-time
        event_id:
          type: string
          format: uuid
        event_client_id:
          type: string
        line_items:
          type: array
          items:
            "$ref": "#/components/schemas/OrderLineItem"
        source:
          type: string
    Cart:
      type: object
      required:
        - store_uuid
        - store_platform
        - customer_signed_in
        - subtotal
        - total
        - subtotal_usd
        - total_usd
        - currency
        - items
        - last_updated_at
      properties:
        store_uuid:
          type: string
          format: uuid
        store_platform:
          type: string
        customer_signed_in:
          type: boolean
        subtotal:
          type: number
          format: double
        total:
          type: number
          format: double
        subtotal_usd:
          type: number
          format: double
        total_usd:
          type: number
          format: double
        currency:
          type: string
        items:
          type: array
          items:
            "$ref": "#/components/schemas/CartItem"
        last_updated_at:
          type: string
          format: date-time
    CartItem:
      type: object
      required:
        - id
        - quantity
        - variant_id
      properties:
        id:
          type: integer
          format: int64
        quantity:
          type: integer
        variant_id:
          type: integer
          format: int64
        discounts:
          type: array
          items:
            type: string
    OrderLineItem:
      type: object
      required:
        - title
        - quantity
        - price
      properties:
        title:
          type: string
        quantity:
          type: integer
        price:
          type: number
          format: double
        sku:
          type: string
        variant_id:
          type: string
        product_id:
          type: string
    SegmentMembership:
      type: object
      required:
        - segment_id
        - is_member
      properties:
        segment_id:
          type: integer
          format: int64
          description:
            ID of the segment definition this membership refers to. The
            built-in segments have the IDs 0 (lead) and 1 (qualified lead).
          example: 0
        is_member:
          type: boolean
          description: Whether the customer currently satisfies the segment's conditions.
          example: true
        membership_last_updated_at:
          type: string
          format: date-time
          description:
            Timestamp of the last time `is_member` changed (the customer
            was added to or removed from the segment).
          example: "2026-07-13T13:11:21.187676Z"
        membership_attribution:
          type: array
          items:
            type: string
          description:
            Account IDs of the agents credited with the customer joining
            the segment. Populated only when an agent-driven update added the customer;
            empty for additions caused by customers setting their own data.
          example:
            - bc35115a-6f12-40b4-bbb0-8187b0f68c8e
        conditions_provenance:
          type: object
          additionalProperties:
            "$ref": "#/components/schemas/ConditionProvenance"
          description:
            Per-condition provenance, keyed by condition name (e.g. `email_set`,
            `phone_number_set`). An entry is present for each condition the customer
            currently satisfies.
          example:
            email_set:
              last_updated_at: "2026-07-15T09:31:45.075731Z"
              agent_account_id: bc35115a-6f12-40b4-bbb0-8187b0f68c8e
              agent_client_id: 71d32c598862b01b9e2298281339dbc2
    ConditionProvenance:
      type: object
      required:
        - last_updated_at
      properties:
        last_updated_at:
          type: string
          format: date-time
          description: Timestamp of when this condition was last satisfied.
          example: "2026-07-13T13:11:21.187676Z"
        agent_account_id:
          type: string
          description:
            Account ID of the agent whose change satisfied this condition.
            Omitted when the change was not attributable to an agent.
          example: bc35115a-6f12-40b4-bbb0-8187b0f68c8e
        agent_client_id:
          type: string
          description:
            Client ID of the application which issued the token for agent
            who satisfied this condition. Omitted when the change was not attributable
            to an agent.
          example: 71d32c598862b01b9e2298281339dbc2
    CustomerPropertyValue:
      type: object
      required:
        - value
        - last_updated_at
      properties:
        value:
          description:
            The property value. Its type depends on the property definition
            (boolean, string, number, timestamp string, link string, or text string).
            Null when the property has been cleared.
          nullable: true
        last_updated_at:
          type: string
          format: date-time
          description: Timestamp of the last update to this property value.
        last_updated_agent_account_id:
          type: string
          description:
            Account ID of the agent that last set this value. Omitted when
            the value was not set by an agent.
        last_updated_agent_client_id:
          type: string
          description:
            Client ID of the application that last set this value. Omitted
            when the value was not set by an agent.
    CustomerPropertyType:
      type: string
      enum:
        - bool
        - string
        - number
        - timestamp
        - link
        - text
      description:
        Type of the customer property value. Assigned at creation and immutable.
        `text` holds free-form multi-line content of up to 5000 characters and does
        not accept `allowed_values`.
    CustomerPropertyTypeConfiguration:
      type: object
      description:
        Per-type configuration. `format` is exclusive to properties of
        type `timestamp` (sending a non-empty `format` for other types is rejected
        with `422`). `allowed_values`, when present, constrains the property to a
        predefined domain; it is rejected with `422` for `text` properties.
      example: {}
      properties:
        format:
          type: string
          enum:
            - date-time
            - date
            - time
          description:
            Optional rendering format for timestamp property values. Aligns
            with JSON Schema format keywords. When empty, raw stored timestamp values
            are returned. Present only for `timestamp` properties and immutable after
            creation.
        allowed_values:
          type: array
          maxItems: 30
          items:
            description:
              A single accepted value, typed to match the property `type`
              (boolean, string, number, or a timestamp/link string). Stored as provided;
              a value being set is matched against this set exactly.
          description:
            Optional domain of accepted values. When present, setting a
            value outside this set is rejected with `422`; `null` (clearing the value)
            is always allowed. The property remains single-valued — this is a set
            of allowed values, not a multi-value type. On create the full set is provided
            wholesale; exact duplicates and empty/`null` entries are rejected, and
            at most 30 entries are allowed. Changing the domain does not backfill
            or alter existing customer values, which are still returned even if they
            no longer match.
    CustomerPropertyTypeConfigurationUpdate:
      type: object
      additionalProperties: false
      description:
        Updates the property's allowed-value domain. Timestamp `format`
        is immutable after property creation.
      example: {}
      properties:
        allowed_values:
          type: array
          maxItems: 30
          items:
            description:
              A single accepted value, typed to match the property `type`
              (boolean, string, number, or a timestamp/link string).
          description:
            Replaces the current domain of accepted values wholesale. Send
            an empty array to clear the domain. Exact duplicates and empty/`null`
            entries are rejected, and at most 30 entries are allowed.
    CustomerProperty:
      type: object
      description:
        A customer property definition. `type_configuration` carries a
        `format` only when `type` is `timestamp`, and may carry `allowed_values` for
        any type; it is an empty object (`{}`) when neither applies.
      required:
        - id
        - name
        - type
        - type_configuration
        - has_value
      example:
        id: 9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11
        name: lifetime_value
        type: number
        type_configuration: {}
        description: Lifetime spend in USD
        has_value: true
      properties:
        id:
          type: string
          format: uuid
          description: UUID generated by the store.
        name:
          type: string
          maxLength: 128
          description: Human-readable property name, unique within the organization.
        type:
          "$ref": "#/components/schemas/CustomerPropertyType"
        type_configuration:
          "$ref": "#/components/schemas/CustomerPropertyTypeConfiguration"
        description:
          type: string
          maxLength: 512
        has_value:
          type: boolean
          description: Whether at least one customer has a value set for this property.
    CreateCustomerPropertyRequest:
      type: object
      required:
        - name
        - type
      properties:
        name:
          type: string
          maxLength: 128
          description: Property name, must be non-empty and unique within the organization.
        type:
          "$ref": "#/components/schemas/CustomerPropertyType"
        type_configuration:
          "$ref": "#/components/schemas/CustomerPropertyTypeConfiguration"
        description:
          type: string
          maxLength: 512
    UpdateCustomerPropertyRequest:
      type: object
      required:
        - id
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the property to update.
        name:
          type: string
          maxLength: 128
          description: New name. Must be unique within the organization.
        description:
          type: string
          maxLength: 512
        type_configuration:
          "$ref": "#/components/schemas/CustomerPropertyTypeConfigurationUpdate"
      description:
        At least one of `name`, `description`, `type_configuration` must
        be provided. The `type` field is intentionally absent — type is immutable,
        and any unknown field (including `type`) causes the request to be rejected
        with a validation error. Within `type_configuration`, only `allowed_values`
        can be updated; timestamp `format` is immutable after property creation.
    DeleteCustomerPropertyRequest:
      type: object
      required:
        - id
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the property to delete.
    ListCustomerPropertiesResponse:
      type: object
      required:
        - properties
      properties:
        last_updated_at:
          type: string
          format: date-time
          description:
            Timestamp of the most recent create or update operation on
            the organization's customer property schema. Omitted when the organization
            has never had any properties.
        last_updated_by:
          type: string
          description:
            Account ID (from the SSO token) of the actor that last mutated
            the schema. Omitted when the organization has never had any properties.
        properties:
          type: array
          items:
            "$ref": "#/components/schemas/CustomerProperty"
    SetCustomerPropertiesValuesRequest:
      type: object
      required:
        - customer_id
        - properties
      additionalProperties: false
      properties:
        customer_id:
          type: string
          description:
            The customer whose property values should be set. Must not
            be empty.
        properties:
          type: object
          additionalProperties:
            description:
              "Property value keyed by property definition ID. The value
              type must match the property's defined type: boolean for `bool`, string
              (max 2048 chars) for `string`, number for `number`, RFC 3339 / date
              / time string for `timestamp` (depending on type configuration format),
              or a valid HTTP(S) URL string (max 2048 chars) for `link`, or string
              (max 5000 chars) for `text`. Use `null` to clear a property value."
          description: A map of property definition IDs to their values.
    UpdateCustomerRequest:
      type: object
      required:
        - customer_id
        - relationship_level
      additionalProperties: false
      properties:
        customer_id:
          type: string
          format: uuid
          description: The customer to update.
        relationship_level:
          type: string
          enum:
            - vip
          nullable: true
          description: Assign `vip` or use `null` to remove the relationship level.
    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: "#/components/schemas/AndSegmentNode"
          or: "#/components/schemas/OrSegmentNode"
          name_set: "#/components/schemas/NameSetSegmentNode"
          email_set: "#/components/schemas/EmailSetSegmentNode"
          phone_number_set: "#/components/schemas/PhoneNumberSetSegmentNode"
          customer_property_set: "#/components/schemas/CustomerPropertySetSegmentNode"
          last_active_days_ago: "#/components/schemas/LastActiveDaysAgoSegmentNode"
    AndSegmentNode:
      type: object
      additionalProperties: false
      required:
        - type
        - nodes
      description: 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:
            Child nodes. An `and` node with no children is a validation
            error.
    OrSegmentNode:
      type: object
      additionalProperties: false
      required:
        - type
        - nodes
      description: 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:
            Child nodes. An `or` node with no children is a validation
            error.
    NameSetSegmentNode:
      type: object
      additionalProperties: false
      required:
        - type
      description:
        True when the customer has a non-empty name that is not a default,
        system-generated name.
      properties:
        type:
          type: string
          enum:
            - name_set
    EmailSetSegmentNode:
      type: object
      additionalProperties: false
      required:
        - type
      description: True when the customer has a non-empty email address.
      properties:
        type:
          type: string
          enum:
            - email_set
    PhoneNumberSetSegmentNode:
      type: object
      additionalProperties: false
      required:
        - type
      description: True when the customer has a non-empty phone number.
      properties:
        type:
          type: string
          enum:
            - phone_number_set
    CustomerPropertySetSegmentNode:
      type: object
      additionalProperties: false
      required:
        - type
        - customer_property_id
      description:
        True when the referenced customer property currently 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:
            ID of the referenced customer property definition. Validated
            as a UUID and checked against the organization's active property schema
            when the containing segment definition is created or updated; a stored
            definition does not become invalid retroactively if the referenced property
            is later archived or deleted.
    LastActiveDaysAgoSegmentNode:
      type: object
      additionalProperties: false
      required:
        - type
        - days
      description:
        True when the customer's last activity was at most `days` days
        ago.
      properties:
        type:
          type: string
          enum:
            - last_active_days_ago
        days:
          type: integer
          minimum: 1
          maximum: 365
          description:
            Number of days, inclusive, since the customer's last recorded
            activity.
    SegmentDefinition:
      type: object
      description:
        A segment definition record, as returned by `get_segment_definitions`
        and by the create/update mutations.
      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:
            Definition ID, unique within the organization. `0` (lead) and
            `1` (qualified lead) are the built-in definitions, present for every organization
            even before they have been edited; custom definitions created through
            the API get IDs from `2` upwards.
          example: 2
        segment_type:
          type: string
          enum:
            - lead
            - qualified_lead
            - custom
          description:
            "`lead` for built-in definition `0`, `qualified_lead` for built-in
            definition `1`, and `custom` for the rest. Fixed for the life of a definition:
            `create_segment_definition` accepts it only to pick which built-in definition
            to restore, and `update_segment_definition` never accepts it."
        definition:
          "$ref": "#/components/schemas/SegmentDefinitionNode"
        referenced_customer_properties_definitions_ids:
          type: array
          items:
            type: string
            format: uuid
          description:
            "`customer_property_id` values referenced anywhere in `definition`,
            deduplicated, in definition order. Derived from the tree on every read,
            so it cannot drift from it. Omitted when the tree has no `customer_property_set`
            node. Includes IDs whose customer-property definition has since been archived
            or deleted, so an agent can find and repair the dangling reference."
        last_updated_at:
          type: string
          format: date-time
          nullable: true
          description:
            Request-handling time of the most recent create or update of
            this definition. Not a commit-order or concurrency token. Null for a built-in
            definition (`0`, `1`) before its first update.
        agent_account_id:
          type: string
          nullable: true
          description:
            Account ID of the agent that last created or updated this definition.
            Null for a built-in definition (`0`, `1`) before its first update.
        agent_client_id:
          type: string
          nullable: true
          description:
            Client ID of the application that last created or updated this
            definition. Null for a built-in definition (`0`, `1`) before its first
            update.
    GetSegmentDefinitionsResponse:
      type: object
      required:
        - segment_definitions
      properties:
        segment_definitions:
          type: array
          items:
            "$ref": "#/components/schemas/SegmentDefinition"
          description:
            Every active definition for the organization, including the
            built-in definitions `0` and `1`, ordered by `segment_id`. A deleted definition
            is absent, so the array can be empty. A built-in ID can disappear and
            later reappear, with a different tree, as it is deleted and restored.
    CreateSegmentDefinitionRequest:
      type: object
      required:
        - definition
      additionalProperties: false
      description:
        Does not accept `segment_id`; the ID is either allocated by the
        store from `2` upwards or fixed by `segment_type`. Supplying `segment_id`,
        including a built-in `0` or `1`, is a validation error.
      properties:
        segment_type:
          type: string
          enum:
            - lead
            - qualified_lead
            - custom
          description:
            Which definition to create. Omitted, or `custom`, allocates
            a new custom definition with the next free ID from `2` upwards. `lead`
            or `qualified_lead` restores that built-in definition at its fixed ID
            (`0` or `1`) with the supplied `definition` tree, consuming no custom
            slot; it requires the built-in to have been deleted, and a still-active
            one is a validation error. Matched case-sensitively; any other value is
            a validation error.
          example: qualified_lead
        definition:
          "$ref": "#/components/schemas/SegmentDefinitionNode"
    UpdateSegmentDefinitionRequest:
      type: object
      required:
        - segment_id
        - definition
      additionalProperties: false
      description:
        Replaces the entire tree of an existing segment definition; partial
        tree updates are not supported. `segment_type` is server-assigned and cannot
        be supplied.
      properties:
        segment_id:
          type: integer
          format: int64
          example: 0
          description:
            ID of the definition to replace. Must be provided explicitly
            — omitting it is a validation error. `0` and `1` are accepted and materialize
            the built-in lead and qualified lead definitions on their first update,
            but a deleted built-in is not found here.
        definition:
          "$ref": "#/components/schemas/SegmentDefinitionNode"
    DeleteSegmentDefinitionRequest:
      type: object
      required:
        - segment_id
      additionalProperties: false
      properties:
        segment_id:
          type: integer
          format: int64
          example: 2
          description:
            ID of the definition to delete. The built-in definitions `0`
            (lead) and `1` (qualified lead) are accepted, whether or not they have
            ever been edited.
    Clause:
      type: object
      required:
        - operator
      properties:
        field:
          type: string
          enum:
            - name
            - email
            - suggested_email
            - phone_number
            - phone_number_country_code
            - country
            - country_code
            - relationship_level
            - segment_id
            - last_activity
            - last_visit_started
            - visits_count
            - page_views_count
            - chats_count
            - threads_count
            - greetings_accepted_count
            - greetings_converted_count
            - tickets_count
            - tickets_inbox_count
            - tickets_archive_count
            - tickets_spam_count
            - tickets_trash_count
            - orders_count
            - cart_last_updated_at
            - cart_total_usd
            - address_street
            - address_city
            - address_country
            - address_state
            - address_postal_code
            - customer_property
          description: |
            Field name to filter on (required for all operators).
            Use `customer_property` to filter on a custom customer property; in that
            case `property_id` is required.
            Use `relationship_level` with operator `is` and value `vip` to filter
            customers with the VIP relationship level.

            Use `segment_id` with operator `is` to filter current segment memberships.
            Each clause accepts `values` (segment IDs, OR-ed), `entered_at` (when the
            customer joined), or both. `entered_at` applies to the same membership as
            `values`; without `values`, it matches membership in any segment. Unknown
            segment IDs are rejected with a validation error. Segment IDs are
            license-specific; request examples use illustrative IDs `5` and `7`.

            The built-in IDs `0` (lead) and `1` (qualified lead) stay valid filters
            even while their definitions are deleted, so fixed-ID clients keep working.
            Memberships are preserved on deletion and are not recomputed, so such a
            clause can still match customers from before the deletion, and can keep
            matching them after a restore with a different tree until the next
            evaluation of that customer.
        property_id:
          type: string
          description: |
            ID of the customer property definition to filter on.
            Required when `field` is `customer_property`; ignored for built-in fields.
            An unknown `property_id` is rejected with a validation error.
          example: db34b1fe-22ce-4d41-bd0b-e15567f4c81b
        entered_at:
          type: object
          description: |
            Narrows a `segment_id` clause to when the customer joined. Ignored for other
            fields. It applies to the same membership as `values`.
            Without `values` it matches a join into any segment. A clause must carry
            `values`, `entered_at`, or both.
          properties:
            from:
              type: string
              format: date-time
              description: |
                Start of the join window, inclusive. Absolute RFC3339 only; relative
                expressions such as `now-7d` are rejected.
              example: "2026-08-01T00:00:00Z"
            to:
              type: string
              format: date-time
              description: End of the join window, inclusive.
              example: "2026-08-06T00:00:00Z"
        operator:
          type: string
          enum:
            - contains
            - is
            - range
            - exists
            - starts_with
          description: |
            Filter operator:
            - `exists`: Check if field exists/is populated (name, email, suggested_email, phone_number, address_street, address_city, address_country, address_state, address_postal_code)
            - `contains`: Partial string matching (name, email, suggested_email, phone_number, address_street, address_city, address_country, address_state, address_postal_code)
            - `is`: Exact match for single or multiple values (all fields)
            - `range`: Range filter for dates, numbers, or cart values (statistics fields, cart fields)
            - `starts_with`: Prefix match (phone_number, address_postal_code)

            For `customer_property` filters, the allowed operators depend on the property's type:
            - `string`: `contains`, `is`, `exists`
            - `link`: `contains`, `is`, `exists`
            - `number`: `range`, `is`, `exists`
            - `timestamp`: `range`, `exists`
            - `bool`: `is`, `exists`
            - `text`: `contains` (matches whole words, no prefix matching), `exists`
        values:
          type: array
          items:
            type: string
          description: |
            Array of values for operators: contains, is, starts_with.
            Multiple values are combined with OR logic.
            Maximum number of elements: 200.
            - For 'starts_with' operator: minimum 3 characters per value
          example:
            - john
            - jane
        range:
          type: object
          properties:
            from:
              oneOf:
                - type: string
                  format: date-time
                - type: integer
                - type: number
                  format: double
              description: |
                Start of range (inclusive, gte).
                For date fields (last_activity, last_visit_started, cart_last_updated_at): use RFC3339 date-time strings (e.g., '2025-01-01T00:00:00Z').
                For timestamp customer properties: use an RFC3339 date-time string regardless of the property's configured format.
                For numeric fields (visits_count, threads_count, etc.): use integers.
                For cart value fields (cart_total_usd): use numbers (e.g., 50.00).
            to:
              oneOf:
                - type: string
                  format: date-time
                - type: integer
                - type: number
                  format: double
              description: |
                End of range (inclusive, lte).
                For date fields (last_activity, last_visit_started, cart_last_updated_at): use RFC3339 date-time strings (e.g., '2025-03-01T00:00:00Z').
                For timestamp customer properties: use an RFC3339 date-time string regardless of the property's configured format.
                For numeric fields (visits_count, threads_count, etc.): use integers.
                For cart value fields (cart_total_usd): use numbers (e.g., 200.00).
          description: |
            Range values for the `range` operator.
            For date fields (last_activity, last_visit_started, cart_last_updated_at), use RFC3339 date-time strings.
            For timestamp customer properties, always use RFC3339 date-time strings. The configured property format controls normalization:
            - `date-time`: compare the represented instant.
            - `date`: compare the RFC3339 value's local calendar date.
            - `time`: compare the RFC3339 value's local wall-clock time.
            For numeric fields (visits_count, threads_count, etc.), use integers.
            For cart value fields (cart_total_usd), use numbers.
          example:
            from: "2025-01-01T00:00:00Z"
            to: "2025-03-01T00:00:00Z"
        negate:
          type: boolean
          default: false
          description: Negate the filter (apply NOT logic)
      example:
        field: name
        operator: contains
        values:
          - john
          - jane
    FilterGroup:
      type: object
      required:
        - operator
        - clauses
      properties:
        operator:
          type: string
          enum:
            - AND
            - OR
          description: The logical operator to combine clauses within this group.
        clauses:
          type: array
          minItems: 1
          description: The filter clauses to be combined with the specified operator.
          items:
            "$ref": "#/components/schemas/Clause"
      example:
        operator: AND
        clauses:
          - field: name
            operator: contains
            values:
              - john
          - field: email
            operator: exists
    CustomerSearchBase:
      type: object
      properties:
        query:
          type: string
          minLength: 3
          description: |
            A free-text search query across `name`, `email`, `suggested_email`, and `phone_number` fields.
            Automatically excludes fields that are explicitly filtered.
            Minimum length: 3 characters.
          example: john smith
        filters:
          type: array
          description: An array of filter groups combined with `AND` logic.
          items:
            "$ref": "#/components/schemas/FilterGroup"
    ListCustomersRequest:
      allOf:
        - "$ref": "#/components/schemas/CustomerSearchBase"
        - type: object
          properties:
            results_per_page:
              type: integer
              minimum: 1
              maximum: 100
              default: 50
              description:
                "The number of results to return per page. \nDefault: 50.
                Maximum: 100.\n"
            sort:
              type: object
              description: |
                The sorting configuration (field -> order mapping).
                Each key is either a sortable field name or a customer property ID, and the key order sets the sort priority.
                Customer properties of type `text` are not sortable.
                Note: `created_at` is always appended as the final sort field to ensure stable pagination.
              additionalProperties:
                type: string
                enum:
                  - asc
                  - desc
              example:
                last_activity: desc
                9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11: asc
            page_id:
              type: string
              description: |
                The page identifier for pagination. Should be a numeric string starting from `"1"`.
                Use the `next_page_id` from the previous response to navigate to the next page.
                Example: `"1"`, `"2"`, `"3"`, etc.
              example: "1"
          example:
            query: john
            filters:
              - operator: AND
                clauses:
                  - field: name
                    operator: contains
                    values:
                      - john
                      - jane
                  - field: email
                    operator: is
                    values:
                      - user@example.com
                      - contact@example.com
                  - field: country_code
                    operator: is
                    values:
                      - US
                    negate: true
                  - field: last_activity
                    operator: range
                    range:
                      from: "2025-01-01T00:00:00Z"
                      to: "2025-03-01T00:00:00Z"
                  - field: threads_count
                    operator: range
                    range:
                      from: 50
                      to: 100
                  - field: cart_total_usd
                    operator: range
                    range:
                      from: 50
                      to: 200
                  - field: cart_last_updated_at
                    operator: range
                    range:
                      from: "2025-01-01T00:00:00Z"
                      to: "2025-03-01T00:00:00Z"
                  - field: segment_id
                    operator: is
                    values:
                      - 0
                    entered_at:
                      from: "2025-01-01T00:00:00Z"
                  - field: customer_property
                    property_id: db34b1fe-22ce-4d41-bd0b-e15567f4c81b
                    operator: is
                    values:
                      - gold
                  - field: customer_property
                    property_id: fa84b317-5b2b-4823-9b51-b7e2868d07b6
                    operator: range
                    range:
                      from: 40
                      to: 50
              - operator: OR
                clauses:
                  - field: name
                    operator: exists
                  - field: email
                    operator: exists
            results_per_page: 50
            sort:
              last_activity: desc
              9b1c9e0a-3a4b-4f0e-9b6f-1f6c8a2b0d11: asc
            page_id: "1"
    ListCustomersResponse:
      type: object
      required:
        - customers
        - total
        - page_id
      properties:
        customers:
          type: array
          items:
            "$ref": "#/components/schemas/Customer"
          description: An array of customer objects matching the search criteria.
        next_page_id:
          type: string
          description: |
            The page identifier for the next page of results.
            Empty string if there are no more pages.
            Pass this value as `page_id` in the next request to retrieve the next page.
          example: "2"
        total:
          type: integer
          format: int32
          description: The total number of customers matching the search criteria.
          example: 1523
        page_id:
          type: string
          description: The current page identifier.
          example: "1"
    GetCustomersCountRequest:
      allOf:
        - "$ref": "#/components/schemas/CustomerSearchBase"