beehiiv Segments API

openapi: 3.2.0
info:
  title: Reference Segments API
  version: 1.0.0
servers:
- url: https://api.beehiiv.com/v2
  description: Default
tags:
- name: Segments
paths:
  /publications/{publicationId}/segments:
    post:
      operationId: create
      summary: Create segment
      description: 'Create a new segment.<br><br> **Manual segments** — Use `subscriptions` or `emails` input to create a segment from an explicit list of subscription IDs or email addresses. The segment is processed synchronously and returns with `status: completed`. Net new email addresses will be ignored; create subscriptions using the `Create Subscription` endpoint.<br><br> **Dynamic segments** — Use `custom_fields` input to create a segment that filters subscribers by custom field values. The segment is processed asynchronously and returns with `status: pending`. Results will be available in the `List Segment Subscribers` endpoint after processing is complete.'
      tags:
      - Segments
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_segments_SegmentShowResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: A unique name for the segment that does not already exist in the publication.
                input:
                  $ref: '#/components/schemas/type_segments_SegmentSubscriptionInput'
              required:
              - name
              - input
    get:
      operationId: index
      summary: 'List segments <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>'
      description: Retrieve information about all segments belonging to a specific publication
      tags:
      - Segments
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: type
        in: query
        description: Optionally filter the results by the segment's type.
        required: false
        schema:
          $ref: '#/components/schemas/type__SegmentType'
      - name: status
        in: query
        description: Optionally filter the results by the segment's status.
        required: false
        schema:
          $ref: '#/components/schemas/type_segments_SegmentRequestStatus'
      - name: limit
        in: query
        description: A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
        required: false
        schema:
          type: integer
      - name: page
        in: query
        description: 'Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.'
        required: false
        schema:
          type: integer
      - name: order_by
        in: query
        description: The field that the results are sorted by. Defaults to created<br> `created` - The time in which the segment was first created.<br> `last_calculated` - The time that the segment last completed calculation. Measured in seconds since the Unix epoch.
        required: false
        schema:
          $ref: '#/components/schemas/type_segments_SegmentOrderBy'
      - name: direction
        in: query
        description: The direction that the results are sorted in. Defaults to asc<br> `asc` - Ascending, sorts from smallest to largest.<br> `desc` - Descending, sorts from largest to smallest.
        required: false
        schema:
          $ref: '#/components/schemas/type__RequestDirection'
      - name: expand[]
        in: query
        description: Optionally expand the response to include additional data. <br> `stats` - Requests the most recently calculated statistics for a segment. <br> Segment stats are recalculated once daily around 7 a.m. UTC for dynamic segments, but can be manually recalculated at any time in the dashboard. Manual and static segments only calculate once upon upload or creation.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/type_segments_SegmentsExpandItems'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_segments_SegmentsListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
  /publications/{publicationId}/segments/{segmentId}:
    get:
      operationId: show
      summary: 'Get segment <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>'
      description: Retrieve information about a specific segment belonging to a publication
      tags:
      - Segments
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: segmentId
        in: path
        description: The prefixed ID of the segment object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_SegmentId'
      - name: expand[]
        in: query
        description: Optionally expand the response to include additional data. <br> `stats` - Requests the most recently calculated statistics for a segment. <br> Segment stats are recalculated once daily around 7 a.m. UTC for dynamic segments, but can be manually recalculated at any time in the dashboard. Manual and static segments only calculate once upon upload or creation.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/type_segments_SegmentsExpandItems'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_segments_SegmentShowResponse'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
    delete:
      operationId: delete
      summary: 'Delete segment <Badge intent="info" minimal outlined>OAuth Scope: segments:write</Badge>'
      description: Delete a segment. Deleting the segment does not effect the subscriptions in the segment.
      tags:
      - Segments
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: segmentId
        in: path
        description: The prefixed ID of the segment object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_SegmentId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_segments_SegmentDeleteResponse'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
  /publications/{publicationId}/segments/{segmentId}/recalculate:
    put:
      operationId: recalculate
      summary: 'Recalculate segment <Badge intent="info" minimal outlined>OAuth Scope: segments:write</Badge>'
      description: Recalculates a specific segment belonging to a publication
      tags:
      - Segments
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: segmentId
        in: path
        description: The prefixed ID of the segment object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_SegmentId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_segments_SegmentRecalculateResponse'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
  /publications/{publicationId}/segments/{segmentId}/members:
    get:
      operationId: list-members
      summary: 'List segment subscribers <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>'
      description: 'List all members in a segment with full subscription data. Each member is returned as a subscription  object containing complete subscriber information and their subscription details.  Supports optional expansions for stats, custom fields, tags, referrals, and premium tiers.

        **Use this endpoint when you need detailed subscriber information.** If you only need subscriber IDs, use `/segments/{segmentId}/results` for a lighter-weight response.'
      tags:
      - Segments
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: segmentId
        in: path
        description: The prefixed ID of the segment object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_SegmentId'
      - name: limit
        in: query
        description: A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
        required: false
        schema:
          type: integer
      - name: page
        in: query
        description: 'Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.'
        required: false
        schema:
          type: integer
      - name: expand[]
        in: query
        description: Optionally expand the response to include additional data. <br> `stats` - Returns statistics about the subscription(s). <br> `custom_fields` - Returns custom field values set on the subscription. <br> `referrals` - Returns referrals made by the subscription. <br> `tags` - Returns tags associated with the subscription. <br> `subscription_premium_tiers` - Returns premium tier(s) the subscription is subscribed to.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/type_segments_SegmentMembersExpandItems'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_segments_SegmentMembersResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
  /publications/{publicationId}/segments/{segmentId}/results:
    get:
      operationId: expand-results
      summary: 'List segment subscriber IDs <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>'
      description: 'List subscriber IDs for a segment. Returns a lightweight array of subscription IDs only, without additional subscriber details.

        **Use this endpoint when you only need subscriber IDs** (e.g., for counting, ID-based lookups, or  integrations with external systems). If you need full subscriber details (email, status, custom fields, etc.), use `/segments/{segmentId}/members` instead.'
      tags:
      - Segments
      parameters:
      - name: publicationId
        in: path
        description: The prefixed ID of the publication object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_PublicationId'
      - name: segmentId
        in: path
        description: The prefixed ID of the segment object
        required: true
        schema:
          $ref: '#/components/schemas/type_ids_SegmentId'
      - name: limit
        in: query
        description: A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.
        required: false
        schema:
          type: integer
      - name: page
        in: query
        description: 'Pagination returns the results in pages. Each page contains the number of results specified by the `limit` (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.'
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_segments_SegmentsGetResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '401':
          description: Unauthorized. The API key or OAuth access token is missing, invalid, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type__Error'
components:
  schemas:
    type__CustomFieldType:
      type: string
      enum:
      - string
      - integer
      - boolean
      - date
      - datetime
      - list
      - double
      description: The type of value being stored in the custom field.
      title: CustomFieldType
    type_segments_SegmentsGetResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: string
          description: An array of subscription ids
        limit:
          type: integer
          description: The limit placed on the results. If no limit was specified in the request,this defaults to 10.
        page:
          type: integer
          default: 1
          description: The page number the results are from. If no page was specified in the request, this defaults to page 1.
        total_results:
          type: integer
          description: The total number of results from all pages.
        total_pages:
          type: integer
          description: The total number of pages.
      required:
      - data
      - limit
      - page
      - total_results
      - total_pages
      title: SegmentsGetResponse
    type_segments_SegmentRequestStatus:
      type: string
      enum:
      - pending
      - processing
      - completed
      - failed
      - all
      default: all
      title: SegmentRequestStatus
    type__Error:
      type: object
      properties:
        status:
          type: integer
        statusText:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/type__ErrorDetail'
      required:
      - status
      - statusText
      - errors
      description: The top level error response.
      title: Error
    type__SubscriptionCustomFieldList:
      type: array
      items:
        $ref: '#/components/schemas/type__CustomField'
      description: 'Optional list of custom fields for a subscription. Retrievable by including `expand: [custom_field]` in the request body.'
      title: SubscriptionCustomFieldList
    type__SubscriptionTierList:
      type: array
      items:
        $ref: '#/components/schemas/type__SubscriptionTierInfo'
      description: 'Optional list of tiers for a subscription. Retrievable by including `expand: [subscription_premium_tiers]` in the request body.'
      title: SubscriptionTierList
    type__SubscriptionTierInfoStatus:
      type: string
      enum:
      - active
      - archived
      description: Returns whether or not the tier has any active prices.
      title: SubscriptionTierInfoStatus
    type__SubscriptionTags:
      type: array
      items:
        type: string
      description: 'Optional list of tags for a subscription. Retrievable by including `expand: [tags]` in the request body.

        Max limit of 100 unique tags per publication.'
      title: SubscriptionTags
    type_segments_SegmentsListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type__Segment'
          description: An array of all segments.
        limit:
          type: integer
          description: The limit placed on the results. If no limit was specified in the request,this defaults to 10.
        page:
          type: integer
          default: 1
          description: The page number the results are from. If no page was specified in the request, this defaults to page 1.
        total_results:
          type: integer
          description: The total number of results from all pages.
        total_pages:
          type: integer
          description: The total number of pages.
      required:
      - data
      - limit
      - page
      - total_results
      - total_pages
      title: SegmentsListResponse
    type__SubscriptionTierInfo:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/type_ids_TierId'
        name:
          type: string
        status:
          $ref: '#/components/schemas/type__SubscriptionTierInfoStatus'
          description: Returns whether or not the tier has any active prices.
      required:
      - id
      - name
      - status
      title: SubscriptionTierInfo
    type__SubscriptionStats:
      type: object
      properties:
        emails_received:
          type: integer
          description: The total number of emails that have been sent to this subscriber
        open_rate:
          type: number
          format: double
          description: The percentage of emails that the subscriber has opened
        click_through_rate:
          type: number
          format: double
          description: The percentage of emails that the subscriber has clicked a link in
      description: 'Optional list of stats for a subscription. Retrievable by including `expand: [stats]` in the request body.'
      title: SubscriptionStats
    type__RequestDirection:
      type: string
      enum:
      - asc
      - desc
      default: asc
      description: The direction of the request. Defaults to `asc`.
      title: RequestDirection
    type_segments_SegmentRecalculateResponse:
      type: object
      properties:
        message:
          type: string
      title: SegmentRecalculateResponse
    type_segments_SegmentDeleteResponse:
      type: object
      properties:
        message:
          type: string
      title: SegmentDeleteResponse
    type__SubscriptionExpandedStatus:
      type: string
      enum:
      - validating
      - invalid
      - pending
      - active
      - inactive
      - needs_attention
      - paused
      description: The status of the subscription.<br>`validating` - The email address is being validated.<br>`invalid` - The email address is invalid.<br>`pending` - The email address is valid, but the subscription is pending double opt-in.<br>`active` - The email was valid and the subscription is active.<br>`inactive` - The subscription was made inactive, possibly due to an unsubscribe.<br>`needs_attention` - The subscription requires approval or denial.<br>`paused` - The subscriber has paused their subscription.
      title: SubscriptionExpandedStatus
    type__CustomField:
      type: object
      properties:
        name:
          type: string
          description: The name of the existing custom field
        kind:
          $ref: '#/components/schemas/type__CustomFieldType'
          description: The type of value being stored in the custom field.
        value:
          $ref: '#/components/schemas/type__CustomFieldDataType'
          description: The value stored for the subscription
      title: CustomField
    type__CustomFieldDataType:
      oneOf:
      - type: string
      - type: number
        format: double
      - type: boolean
      - type: array
        items:
          type: string
      title: CustomFieldDataType
    type_segments_SegmentMembersResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type__Subscription'
        limit:
          type: integer
          description: The limit placed on the results. If no limit was specified in the request,this defaults to 10.
        page:
          type: integer
          default: 1
          description: The page number the results are from. If no page was specified in the request, this defaults to page 1.
        total_results:
          type: integer
          description: The total number of results from all pages.
        total_pages:
          type: integer
          description: The total number of pages.
      required:
      - data
      - limit
      - page
      - total_results
      - total_pages
      title: SegmentMembersResponse
    type__SegmentType:
      type: string
      enum:
      - dynamic
      - static
      - manual
      - all
      default: all
      description: The type of segment.<br>`dynamic` - The segment is recalculated at set intervals.<br>`static` - The segment is calculated once at creation.<br>`manual` - The segment is not calculated at all. The results are created via CSV.
      title: SegmentType
    type__SegmentStats:
      type: object
      properties:
        open_rate:
          type: number
          format: double
          description: The average open rate of the subscribers in the segment.
        total_sent:
          type: integer
          description: The total number of emails sent to the subscribers in the segment.
        percentage_premium_subscribers:
          type: number
          format: double
          description: The percentage of subscribers in this segment who are premium in any tier.
        percentage_subscribers_with_referrals:
          type: number
          format: double
          description: The percentage of subscribers in this segment who have referred at least one other subscriber.
        unique_emails_clicked:
          type: integer
          description: The total number of unique emails clicked by subscribers in the segment.
        total_delivered:
          type: integer
          description: The total number of emails delivered to subscribers in the segment.
        total_referrals:
          type: integer
          description: The total number of referrals from subscribers in the segment.
        unsubscribed_rate:
          type: number
          format: double
          description: The percentage of subscribers in this segment who have unsubscribed.
        total_subscribers:
          type: integer
          description: The total number of subscribers in the segment.
        clickthrough_rate:
          type: number
          format: double
          description: The average clickthrough rate of the subscribers in the segment.
        unsubscribed_count:
          type: integer
          description: The total number of subscribers in the segment who are unsubscribed.
        unique_emails_opened:
          type: integer
          description: The total number of unique emails opened by subscribers in the segment.
        premium_subscribers:
          type: integer
          description: The total number of premium subscribers in the segment.
        average_referrals_per_subscriber:
          type: number
          format: double
          description: The average number of referrals per subscriber in the segment.
      required:
      - open_rate
      - total_sent
      - percentage_premium_subscribers
      - percentage_subscribers_with_referrals
      - unique_emails_clicked
      - total_delivered
      - total_referrals
      - unsubscribed_rate
      - total_subscribers
      - clickthrough_rate
      - unsubscribed_count
      - unique_emails_opened
      - premium_subscribers
      - average_referrals_per_subscriber
      title: SegmentStats
    type_segments_SegmentShowResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type__Segment'
      required:
      - data
      title: SegmentShowResponse
    type__ErrorDetail:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
      required:
      - message
      - code
      title: ErrorDetail
    type_segments_SegmentsExpandItems:
      type: string
      enum:
      - stats
      title: SegmentsExpandItems
    type__SubscriptionExpandedUtmChannel:
      type: string
      enum:
      - ''
      - website
      - import
      - embed
      - api
      - referral
      - recommendation
      - magic_link
      - boost
      - boost_send
      - boost_direct_link
      - integration
      - product
      - group_invite
      description: The acquisition channel
      title: SubscriptionExpandedUtmChannel
    type_segments_CustomFieldFilter:
      type: object
      properties:
        name:
          type: string
          description: The display name of the custom field (case-insensitive match). Must be an existing custom field on the publication.
        operator:
          type: string
          description: The comparison operator for the filter (e.g., `equal`, `not_equal`, `contains`, `exists`, `does_not_exist`). Available operators depend on the custom field's type.
        value:
          type: string
          description: The value to compare against. Required for all operators except `exists` and `does_not_exist`.
      required:
      - name
      - operator
      description: A single custom field fi

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/beehiiv/refs/heads/main/openapi/beehiiv-segments-api-openapi.yml