{
  "opencollection": "1.0.0",
  "info": {
    "name": "API Reference subpackage_advertisement_opportunities subpackage_segments API",
    "version": "1.0.0"
  },
  "items": [
    {
      "info": {
        "name": "subpackage_segments",
        "type": "folder"
      },
      "items": [
        {
          "info": {
            "name": "List segments <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:read</Badge>",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/segments",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "type",
                "value": "",
                "type": "query",
                "description": "Optionally filter the results by the segment's type."
              },
              {
                "name": "status",
                "value": "",
                "type": "query",
                "description": "Optionally filter the results by the segment's status."
              },
              {
                "name": "limit",
                "value": "",
                "type": "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."
              },
              {
                "name": "page",
                "value": "",
                "type": "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."
              },
              {
                "name": "order_by",
                "value": "",
                "type": "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."
              },
              {
                "name": "direction",
                "value": "",
                "type": "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."
              },
              {
                "name": "expand[]",
                "value": "",
                "type": "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."
              }
            ]
          },
          "docs": "Retrieve information about all segments belonging to a specific publication"
        },
        {
          "info": {
            "name": "Create segment",
            "type": "http"
          },
          "http": {
            "method": "POST",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/segments",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              }
            ],
            "body": {
              "type": "json",
              "data": "{}"
            }
          },
          "docs": "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 proces"
        },
        {
          "info": {
            "name": "Get segment <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:read</Badge>",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/segments/:segmentId",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "segmentId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the segment object"
              },
              {
                "name": "expand[]",
                "value": "",
                "type": "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."
              }
            ]
          },
          "docs": "Retrieve information about a specific segment belonging to a publication"
        },
        {
          "info": {
            "name": "Delete segment <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:write</Badge>",
            "type": "http"
          },
          "http": {
            "method": "DELETE",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/segments/:segmentId",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "segmentId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the segment object"
              }
            ]
          },
          "docs": "Delete a segment. Deleting the segment does not effect the subscriptions in the segment."
        },
        {
          "info": {
            "name": "Recalculate segment <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:write</Badge>",
            "type": "http"
          },
          "http": {
            "method": "PUT",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/segments/:segmentId/recalculate",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "segmentId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the segment object"
              }
            ]
          },
          "docs": "Recalculates a specific segment belonging to a publication"
        },
        {
          "info": {
            "name": "List segment subscribers <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:read</Badge>",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/segments/:segmentId/members",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "segmentId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the segment object"
              },
              {
                "name": "limit",
                "value": "",
                "type": "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."
              },
              {
                "name": "page",
                "value": "",
                "type": "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."
              },
              {
                "name": "expand[]",
                "value": "",
                "type": "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."
              }
            ]
          },
          "docs": "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.\n**Use this endpoint when you need detailed subscriber information.** If you only need subscriber IDs, use `/segments/{segmentId}/results` for a lighter-weight response."
        },
        {
          "info": {
            "name": "List segment subscriber IDs <Badge intent=\"info\" minimal outlined>OAuth Scope: segments:read</Badge>",
            "type": "http"
          },
          "http": {
            "method": "GET",
            "url": "https://api.beehiiv.com/v2/publications/:publicationId/segments/:segmentId/results",
            "headers": [
              {
                "name": "Authorization",
                "value": ""
              }
            ],
            "params": [
              {
                "name": "publicationId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the publication object"
              },
              {
                "name": "segmentId",
                "value": "",
                "type": "path",
                "description": "The prefixed ID of the segment object"
              },
              {
                "name": "limit",
                "value": "",
                "type": "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."
              },
              {
                "name": "page",
                "value": "",
                "type": "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."
              }
            ]
          },
          "docs": "List subscriber IDs for a segment. Returns a lightweight array of subscription IDs only, without additional subscriber details.\n**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."
        }
      ]
    }
  ],
  "bundled": true
}