beehiiv Developer Documentation

import requests
url = "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/segments"
payload = {
    "name": "My Segment",
    "input": {
        "type": "subscriptions",
        "subscriptions": ["sub_00000000-0000-0000-0000-000000000000", "sub_00000000-1111-1111-1111-111111111111"]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "data": {
    "id": "seg_00000000-0000-0000-0000-000000000000",
    "name": "My Segment",
    "type": "manual",
    "total_results": 2,
    "status": "completed",
    "active": true,
    "last_calculated": 1666800076
  }
}

Create a new segment.

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.

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.

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.

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

Request

This endpoint expects an object.

namestringRequired

A unique name for the segment that does not already exist in the publication.

inputobjectRequired

Input for segment creation. Use subscriptions or emails to create a manual segment from explicit lists, or custom_fields to create a dynamic segment filtered by custom field values.

Response

Created

dataobject

The segment object. To expand results, see the results endpoint.

Errors

400

Bad Request Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error