beehiiv Developer Documentation

{
  "data": [
    {
      "id": "sub_00000000-0000-0000-0000-000000000000",
      "email": "subscriber@example.com",
      "status": "active",
      "created": 1666800076,
      "subscription_tier": "free",
      "subscription_premium_tier_names": [],
      "utm_source": "twitter",
      "utm_medium": "social",
      "utm_channel": "website",
      "utm_campaign": "spring_2023",
      "utm_term": "",
      "utm_content": "",
      "referring_site": "https://twitter.com",
      "referral_code": "ABC123"
    }
  ],
  "limit": 10,
  "page": 1,
  "total_results": 1,
  "total_pages": 1
}

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

segmentIdstringRequiredformat: "^(seg_[0-9a-fA-F\-]+)$"

The prefixed ID of the segment object

Query parameters

limitintegerOptional

A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.

pageintegerOptional

Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10).
If not specified, results 1-10 from page 1 will be returned.

expand[]list of enumsOptional

Optionally expand the response to include additional data.
stats - Returns statistics about the subscription(s).
custom_fields - Returns custom field values set on the subscription.
referrals - Returns referrals made by the subscription.
tags - Returns tags associated with the subscription.
subscription_premium_tiers - Returns premium tier(s) the subscription is subscribed to.

Allowed values:

Response

datalist of objects

limitinteger

The limit placed on the results. If no limit was specified in the request,this defaults to 10.

pageinteger>=0Defaults to 1

The page number the results are from. If no page was specified in the request, this defaults to page 1.

total_resultsinteger

The total number of results from all pages.

total_pagesinteger

The total number of pages.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error