> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bevits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview segment

> Counts and samples the customers who match the conditions right now, without saving anything, and reports how many can be reached on WhatsApp and by email. Errors name each invalid condition with the valid options. Requires an API key with the read scope.



## OpenAPI

````yaml /openapi.en.json post /v1/segment-builder/preview
openapi: 3.1.0
info:
  title: Bevits API
  version: 1.0.0
  description: >-
    Public API for querying CRM, purchase, and automation data from a Bevits
    organization, creating automations as drafts for review and activation,
    creating WhatsApp Official campaigns as drafts, and building customer
    segments and tags.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.bevits.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: System
    description: API availability.
  - name: Identity
    description: Organization and API key identity.
  - name: Customers
    description: Customers and their relationships.
  - name: Segments
    description: Customer segments.
  - name: Purchases
    description: Purchases imported from integrations.
  - name: CRM data
    description: Tags and attribute definitions.
  - name: Automations
    description: Automation flows.
  - name: Campaigns
    description: Email campaigns.
  - name: Account and brand
    description: Account context, brand identity, and images.
  - name: Recipes
    description: Ready-made automations created from recipes, with undo.
  - name: Email templates
    description: Creating and importing email templates.
  - name: Events
    description: Custom events sent by the store and their types.
paths:
  /v1/segment-builder/preview:
    post:
      tags:
        - Segments
      summary: Preview segment
      description: >-
        Counts and samples the customers who match the conditions right now,
        without saving anything, and reports how many can be reached on WhatsApp
        and by email. Errors name each invalid condition with the valid options.
        Requires an API key with the read scope.
      operationId: previewSegment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentPreviewRequest'
            example:
              match: all
              conditions:
                - kind: coupon
                  status: has_available
                  source: cashback
                  expires_within_days: 7
                - kind: field
                  field: totalSpentInCents
                  operator: gte
                  value: 50000
      responses:
        '200':
          $ref: '#/components/responses/SegmentPreview'
        '400':
          $ref: '#/components/responses/InvalidBody'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ReadScopeRequired'
        '422':
          $ref: '#/components/responses/SegmentValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    SegmentPreviewRequest:
      type: object
      required:
        - conditions
      properties:
        match:
          $ref: '#/components/schemas/SegmentMatch'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/SegmentCondition'
          minItems: 1
          maxItems: 30
          description: >-
            Conditions from the filter catalog (GET
            /v1/segment-builder/catalog). Up to 30.
        sample_size:
          type: integer
          minimum: 0
          maximum: 20
          default: 5
          description: Number of customers in the sample.
    SegmentMatch:
      type: string
      enum:
        - all
        - any
      description: >-
        all: customers who match every condition. any: customers who match at
        least one.
    SegmentCondition:
      description: >-
        One condition of a filter segment. The same format goes into create,
        update, and preview and comes back in GET /v1/segments/{segment_id}.
      oneOf:
        - $ref: '#/components/schemas/SegmentFieldCondition'
        - $ref: '#/components/schemas/SegmentTagsCondition'
        - $ref: '#/components/schemas/SegmentProductCondition'
        - $ref: '#/components/schemas/SegmentCouponCondition'
      discriminator:
        propertyName: kind
        mapping:
          field: '#/components/schemas/SegmentFieldCondition'
          tags: '#/components/schemas/SegmentTagsCondition'
          product: '#/components/schemas/SegmentProductCondition'
          coupon: '#/components/schemas/SegmentCouponCondition'
    SegmentPreview:
      type: object
      required:
        - object
        - customer_count
        - whatsapp_reachable_count
        - email_reachable_count
        - match
        - conditions
        - sample
        - evaluated_at
      properties:
        object:
          type: string
          const: segment_preview
        customer_count:
          type: integer
          minimum: 0
        whatsapp_reachable_count:
          type: integer
          minimum: 0
          description: Matching customers with a phone who did not opt out.
        email_reachable_count:
          type: integer
          minimum: 0
          description: Matching customers with an email who are subscribed to emails.
        match:
          $ref: '#/components/schemas/SegmentMatch'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/SegmentCondition'
        sample:
          type: array
          items:
            $ref: '#/components/schemas/SegmentSampleCustomer'
        evaluated_at:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    RateLimitErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          required:
            - retry_after
          properties:
            retry_after:
              type: integer
              minimum: 1
              description: Seconds before retrying.
    SegmentFieldCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - field
        - operator
      properties:
        kind:
          type: string
          const: field
        field:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            A customer field (such as totalSpentInCents, lastPurchaseDate, or
            city) or the ID of a custom attribute (atr_...), from the filter
            catalog.
        operator:
          type: string
          minLength: 1
          maxLength: 32
          description: >-
            One of the field's operators in the catalog. Text: eq, neq, in,
            not_in, contains, not_contains, starts_with, is_null, is_not_null.
            Number: eq, neq, gt, gte, lt, lte. Boolean: eq_true, eq_false,
            is_null, is_not_null. Date: gt, lt, between.
        value:
          description: >-
            Leave it out for is_null, is_not_null, eq_true, and eq_false. A list
            for in and not_in. Money in cents. Dates in ISO 8601 with a
            timezone.
          oneOf:
            - type: string
              maxLength: 512
            - type: number
            - type: boolean
            - type: array
              items:
                type: string
                minLength: 1
                maxLength: 256
              minItems: 1
              maxItems: 500
        value_to:
          description: End of a between range.
          oneOf:
            - type: string
              maxLength: 64
            - type: number
    SegmentTagsCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - operator
        - tag_ids
      properties:
        kind:
          type: string
          const: tags
        operator:
          type: string
          enum:
            - has_any
            - has_all
            - has_none
          description: >-
            has_any: has any of the tags. has_all: has all of them. has_none:
            has none of them, including customers without any tag.
        tag_ids:
          type: array
          items:
            type: string
            pattern: ^tag_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 50
          description: Tag IDs (tag_...), from GET /v1/tags.
    SegmentProductCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - operator
      properties:
        kind:
          type: string
          const: product
        operator:
          type: string
          enum:
            - has_purchased
            - has_not_purchased
            - purchased_in_category
        product_id:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            The store's product ID, as in purchase items. For has_purchased and
            has_not_purchased.
        category:
          type: string
          minLength: 1
          maxLength: 256
          description: Product category name. For purchased_in_category.
    SegmentCouponCondition:
      type: object
      additionalProperties: false
      required:
        - kind
        - status
      description: >-
        Coupons and cashback (giftback) Bevits issued to the customer in
        automations, in AI customer service, and in in-store sales.
      properties:
        kind:
          type: string
          const: coupon
        status:
          type: string
          enum:
            - has_available
            - has_unused
            - has_expired_unused
            - has_used
            - has_received
            - has_not_received
          description: >-
            has_available: has an unused, unexpired coupon, with credit to spend
            now. has_unused: has a coupon they never used, expired or not.
            has_expired_unused: let a coupon expire without using it. has_used:
            used a coupon in a purchase. has_received: received a coupon.
            has_not_received: never received a coupon.
        source:
          type: string
          enum:
            - cashback
            - any
            - flows
          default: cashback
          description: >-
            cashback: coupons generated by a purchase (cashback or giftback,
            online or in store). any: every coupon Bevits issued to the
            customer. flows: only the coupons of the automations in flow_ids.
        flow_ids:
          type: array
          items:
            type: string
            pattern: ^flw_[A-Za-z0-9_-]+$
          minItems: 1
          maxItems: 50
          description: >-
            With source flows: automations that issue coupons, listed in the
            catalog.
        received_within_days:
          type: integer
          minimum: 1
          maximum: 3650
          description: Only coupons issued in the last N days.
        expires_within_days:
          type: integer
          minimum: 1
          maximum: 365
          description: 'With has_available: only coupons that expire in the next N days.'
    SegmentSampleCustomer:
      type: object
      required:
        - object
        - id
      properties:
        object:
          type: string
          const: customer
        id:
          type: string
          pattern: ^cus_[A-Za-z0-9_-]+$
        name:
          type: string
        email:
          type: string
        phone:
          type: string
    Error:
      type: object
      required:
        - type
        - message
        - request_id
      properties:
        type:
          type: string
          enum:
            - authentication_error
            - conflict
            - internal_error
            - invalid_request
            - not_found
            - permission_denied
            - rate_limited
            - validation_error
        code:
          type: string
          description: >-
            Stable, machine-readable reason within type, such as
            invalid_event_name. Present when the error has a named reason.
        message:
          type: string
        param:
          type: string
          description: >-
            Full path of the offending field, such as customer.email or
            events[3].name.
        suggestion:
          type: string
          description: A value that would be accepted, when there is an obvious one.
        request_id:
          type: string
          pattern: ^req_[a-f0-9]{24}$
  responses:
    SegmentPreview:
      description: Segment preview. Nothing was saved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SegmentPreview'
    InvalidBody:
      description: >-
        Missing request body, a body that is not a JSON object, or an invalid
        route parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing, invalid, expired, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: authentication_error
              message: Invalid API key.
              request_id: req_07f6cdc3c20249d6afcd90b4
    ReadScopeRequired:
      description: >-
        The API key does not have the read scope. This is the case of a
        send-only key, created with events:write alone.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              type: permission_denied
              code: missing_scope
              message: This API key does not have the required "read" scope.
              param: scope
              request_id: req_07f6cdc3c20249d6afcd90b4
    SegmentValidationError:
      description: >-
        A condition or field was rejected, for example an operator that doesn't
        apply to the field or an RFM segment. The message says what to fix and
        the valid options, and error.param points to the field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Request limit exceeded.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RetryAfter:
      description: Seconds before retrying.
      schema:
        type: integer
        minimum: 1
    RateLimitLimit:
      description: Total limit for the current window.
      schema:
        type: integer
        example: 600
    RateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
        example: 599
    RateLimitReset:
      description: UTC instant when the current window ends.
      schema:
        type: string
        format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bvt_live_...
      description: API key created in the organization settings.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.