Sequenzy Segments API

openapi: 3.2.0
info:
  title: Sequenzy Segments API
  description: Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails
  version: 1.0.0
servers:
- url: https://api.sequenzy.com/api/v1
  description: Production server
- url: https://api.sequenzy.com/v1
  description: Legacy production server alias
security:
- bearerAuth: []
tags:
- name: Segments
paths:
  /segments:
    get:
      summary: List segments
      description: Lists saved segments with counts recalculated from their filters for the authenticated company. subscriberCount includes every status; activeSubscriberCount includes only active subscribers. Custom-attribute updates sync asynchronously and may take roughly 30–35 seconds or longer to appear, even after an import completes.
      operationId: listSegments
      tags:
      - Segments
      responses:
        '200':
          description: Segments returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  segments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Segment'
        '400':
          $ref: '#/components/responses/SegmentReferenceLimitExceeded'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
    post:
      summary: Create segment
      description: Creates a saved segment from either flat filters or a nested filter root.
      operationId: createSegment
      tags:
      - Segments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                filters:
                  type: array
                  description: Legacy v1 flat filter shape. Provide either filters or root.
                  items:
                    $ref: '#/components/schemas/FilterLeaf'
                filterJoinOperator:
                  type: string
                  enum:
                  - and
                  - or
                root:
                  description: Nested v2 filter tree. Provide either root or filters.
                  $ref: '#/components/schemas/FilterGroup'
              required:
              - name
              anyOf:
              - required:
                - filters
              - required:
                - root
      responses:
        '200':
          description: Segment created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  segment:
                    $ref: '#/components/schemas/Segment'
                  warnings:
                    type: array
                    description: Non-fatal cautions, such as an attribute filter referencing a custom attribute no subscriber has a synced value for (which would match no subscribers, or every subscriber for exclusion operators like is_empty). Absent when there is nothing to warn about.
                    items:
                      type: string
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidTagOperator:
                  value:
                    success: false
                    error: 'Operator "is not" is not supported for Tag filters. Use one of: contains, does not contain, is empty, is not empty.'
                malformedFilterTree:
                  value:
                    success: false
                    error: 'Invalid segment filters: root.children[1].children: must be an array of filters and groups'
                    issues:
                    - path: root.children[1].children
                      message: must be an array of filters and groups
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Segment name conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentFriendlyError'
  /segments/{segmentId}:
    patch:
      summary: Update segment
      description: Updates a saved segment's name or filter definition.
      operationId: updateSegment
      tags:
      - Segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                filters:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterLeaf'
                filterJoinOperator:
                  type: string
                  enum:
                  - and
                  - or
                root:
                  $ref: '#/components/schemas/FilterGroup'
      responses:
        '200':
          description: Segment updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  segment:
                    $ref: '#/components/schemas/Segment'
                  warnings:
                    type: array
                    description: Non-fatal cautions, such as an attribute filter referencing a custom attribute no subscriber has a synced value for (which would match no subscribers, or every subscriber for exclusion operators like is_empty). Absent when there is nothing to warn about.
                    items:
                      type: string
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidTagOperator:
                  value:
                    success: false
                    error: 'Operator "is not" is not supported for Tag filters. Use one of: contains, does not contain, is empty, is not empty.'
                malformedFilterTree:
                  value:
                    success: false
                    error: 'Invalid segment filters: root.children[1].children: must be an array of filters and groups'
                    issues:
                    - path: root.children[1].children
                      message: must be an array of filters and groups
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Segment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteSegment
      summary: Delete segment
      description: Deletes a saved segment. Subscribers matched by the segment are not affected.
      tags:
      - Segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
        description: Segment ID.
      responses:
        '200':
          description: Segment deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Segment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
  /segments/{segmentId}/count:
    get:
      summary: Get segment count
      description: Recalculates the active subscriber count from a saved segment's filters. Matches activeSubscriberCount from listSegments when underlying data is unchanged. Custom-attribute updates sync asynchronously and may take roughly 30–35 seconds or longer to appear, even after an import completes.
      operationId: getSegmentCount
      tags:
      - Segments
      parameters:
      - name: segmentId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Segment count returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  segmentId:
                    type: string
                  count:
                    type: integer
        '400':
          $ref: '#/components/responses/SegmentReferenceLimitExceeded'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Segment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
components:
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  schemas:
    FilterLeaf:
      type: object
      description: A single subscriber filter rule.
      properties:
        kind:
          type: string
          enum:
          - filter
          description: Required when the filter is inside a v2 root group.
        id:
          type: string
          example: filter-1
        field:
          type: string
          enum:
          - status
          - phone
          - smsStatus
          - tag
          - email
          - emailProvider
          - added
          - firstName
          - lastName
          - list
          - attribute
          - event
          - segment
          - stripeProduct
          - stripeCurrentProduct
          - stripeTrialProduct
          - commerceProduct
          - commerceCollection
          - emailSent
          - emailDelivered
          - emailOpened
          - emailClicked
          - emailBounced
          - emailComplained
          - pushDevice
          - pushSent
          - pushDelivered
          - pushClicked
        operator:
          type: string
          description: 'Valid operators depend on the field. status/segment: is, is_not. smsStatus: is, is_not (values: subscribed, unsubscribed, not_subscribed). phone: is_not_empty, is_empty (empty value). tag: contains, not_contains, is_empty, is_not_empty. email: contains, not_contains for domain or substring matching, is, is_not for an exact case-insensitive address. emailProvider/list: is, is_not, is_empty, is_not_empty. firstName/lastName: contains, not_contains, is_empty, is_not_empty. added: less_than, more_than. attribute: is, is_not, is_empty, is_not_empty, gte, lte, gt, lt, contains, not_contains. event and email engagement fields: is, is_not, at_least, less_than_count. emailBounced also supports is_temporary_bounce and is_permanent_bounce. stripeProduct: is, is_not, at_least, less_than_count. stripeCurrentProduct/stripeTrialProduct: is, is_not, gte, lte, gt, lt. commerceProduct/commerceCollection: is, is_not, at_least, less_than_count. pushDevice: is, is_not (values: any, web, ios, android; matches active push devices). pushSent/pushDelivered/pushClicked: is, is_not with a time range such as 30d or all (test sends are ignored).'
          enum:
          - is
          - is_not
          - is_empty
          - is_not_empty
          - contains
          - not_contains
          - less_than
          - more_than
          - is_temporary_bounce
          - is_permanent_bounce
          - at_least
          - less_than_count
          - gte
          - lte
          - gt
          - lt
        value:
          type: string
          description: Event filters use `eventName:30d` or `eventName:5:30d`. Segment filters use a segment ID. Email engagement fields use a rolling time window (`24h`, `7d`, `30d`, `90d`, `180d`, `all`; whole hours from `1h` to `8760h` are measured to the exact hour; count filters are exact up to `168h`), a specific campaign via `campaign:<campaign_id>`, an email-type scope via `marketing:<timeRange>` (marketing-policy campaign, automation, and Send API traffic) or `transactional:<timeRange>` (transactional-policy sends; with is/is_not or the emailBounced subtype operators; scopes require a send-time policy snapshot, so ambiguous older events remain unscoped), or `count:timeRange` (such as `10:30d` or `10:all`) with at_least/less_than_count. Stripe product filters use `prod_123` for bought/current/trialing checks, `prod_123:3` for payment thresholds, and product-scoped values such as `prod_123:is_canceled`, `prod_123:cancels_at:2026-05-26`, `prod_123:end_at:2026-05-26`, or `prod_123:start_at:7 days ago`. Commerce product filters use `provider:productId` (provider one of `shopify`, `woocommerce`, `api`), optionally with an order-count threshold (`shopify:42:2`); a bare product ID matches the ID on any provider. Commerce collection filters use a collection ID or handle (`skincare`), optionally provider-prefixed and/or with an order-count threshold (`shopify:skincare:2`), and match anyone whose orders contain any product currently in that collection. Push device filters use `any`, `web`, `ios`, or `android`. Push sent, delivered, and clicked filters use a time range (`7d`, `30d`, `all`).
      required:
      - id
      - field
      - operator
      - value
    AgentFriendlyError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Stable machine-readable error code.
          example: SEGMENT_NAME_ALREADY_EXISTS
        error:
          type: string
          description: Short error label.
          example: Segment name already exists
        title:
          type: string
          description: UI-friendly title.
          example: Segment name already exists
        description:
          type: string
          description: Agent-friendly explanation of why the request failed.
          example: A saved segment with this name already exists in this company.
        resolution:
          type: string
          description: Concrete next step for humans or AI agents.
          example: Call list_segments before creating, reuse the existing segment id, or retry with a different name.
        docsUrl:
          type: string
          format: uri
          description: Documentation URL for the failed operation.
          example: https://docs.sequenzy.com/api-reference/segments/create
        details:
          type: object
          additionalProperties: true
      required:
      - success
      - code
      - error
      - title
      - description
      - resolution
      - docsUrl
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          description: Optional stable machine-readable error discriminator when available.
          example: COMPANY_CREATE_REQUIRES_PERSONAL_KEY
        retryable:
          type: boolean
          description: Whether retrying the request can recover from the error.
        issues:
          type: array
          description: Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.
          items:
            $ref: '#/components/schemas/InputIssue'
      required:
      - error
    Segment:
      type: object
      properties:
        id:
          type: string
          example: seg_active_buyers
        name:
          type: string
          example: Active buyers
        filters:
          type: array
          description: Legacy v1 flat filters, or flattened leaves for v2 responses.
          items:
            $ref: '#/components/schemas/FilterLeaf'
        filterJoinOperator:
          type: string
          enum:
          - and
          - or
        format:
          type: string
          enum:
          - v1
          - v2
        root:
          anyOf:
          - allOf:
            - $ref: '#/components/schemas/FilterGroup'
          - type: 'null'
        subscriberCount:
          type: integer
        activeSubscriberCount:
          type: integer
    FilterGroup:
      type: object
      description: A nested AND/OR filter group.
      properties:
        kind:
          type: string
          enum:
          - group
        id:
          type: string
          example: root
        joinOperator:
          type: string
          enum:
          - and
          - or
        children:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/FilterLeaf'
            - $ref: '#/components/schemas/FilterGroup'
            discriminator:
              propertyName: kind
              mapping:
                filter: '#/components/schemas/FilterLeaf'
                group: '#/components/schemas/FilterGroup'
      required:
      - kind
      - id
      - joinOperator
      - children
    InputIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.
          example: kind
        message:
          type: string
          description: What is wrong with the field.
          example: must be "add_tags"
        allowedValues:
          type: array
          description: Accepted values when the field only takes a fixed set of values.
          items: {}
          example:
          - add_tags
      required:
      - path
      - message
  responses:
    TransientDatabaseUnavailable:
      description: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: The service could not reach its database for a moment. Retry the request.
            code: SERVICE_UNAVAILABLE
    SegmentReferenceLimitExceeded:
      description: 'The segment''s filters follow too many segment-to-segment references: more than 16 levels in one chain (SEGMENT_REFERENCE_DEPTH_EXCEEDED), or more than 1,000 references in total, counting a segment again each time it is referenced (SEGMENT_REFERENCE_COUNT_EXCEEDED). Nested filter groups inside a segment do not count. Retrying does not help; reduce the nesting or the number of references first. title and howToFix differ per code.'
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/Error'
            - type: object
              properties:
                code:
                  type: string
                  enum:
                  - SEGMENT_REFERENCE_DEPTH_EXCEEDED
                  - SEGMENT_REFERENCE_COUNT_EXCEEDED
                title:
                  type: string
                  example: Segment references nested too deeply
                description:
                  type: string
                  description: Same explanation as error.
                howToFix:
                  type: string
                docsUrl:
                  type: string
                details:
                  type: object
                  properties:
                    limit:
                      type: string
                      enum:
                      - depth
                      - total
                    segmentId:
                      type: string
                      description: Referenced segment that exceeded the limit.
                    referenceChain:
                      type: array
                      items:
                        type: string
                      description: Segment IDs already followed to reach segmentId, outermost first. Does not include the segment being counted.
                    maxDepth:
                      type: integer
                      example: 16
                    maxReferences:
                      type: integer
                      example: 1000
          example:
            success: false
            error: 'Segment references are nested too deeply. A segment filter can reference other segments up to 16 levels deep, and the reference to segment seg_r would be level 17 (chain: seg_b > seg_c > ... > seg_q > seg_r). Retrying does not help. Copy the conditions of an inner segment into its parent instead of referencing it to reduce the nesting.'
            code: SEGMENT_REFERENCE_DEPTH_EXCEEDED
            title: Segment references nested too deeply
            description: 'Segment references are nested too deeply. A segment filter can reference other segments up to 16 levels deep, and the reference to segment seg_r would be level 17 (chain: seg_b > seg_c > ... > seg_q > seg_r). Retrying does not help. Copy the conditions of an inner segment into its parent instead of referencing it to reduce the nesting.'
            howToFix: Retrying does not help. Copy the conditions of an inner segment into its parent instead of referencing it to reduce the nesting.
            docsUrl: https://docs.sequenzy.com/api-reference/segments/count
            details:
              limit: depth
              segmentId: seg_r
              referenceChain:
              - seg_b
              - seg_c
              - seg_d
              - seg_e
              - seg_f
              - seg_g
              - seg_h
              - seg_i
              - seg_j
              - seg_k
              - seg_l
              - seg_m
              - seg_n
              - seg_o
              - seg_p
              - seg_q
              maxDepth: 16
              maxReferences: 1000
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token