For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
LoginStart trialGet a demo
  • Welcome
    • Getting Started
    • Create an API Key
    • Pagination
    • Rate Limiting
    • No-Code Integrations
  • Webhooks
  • OAuth2
  • API Reference
      • POSTCreate segment
      • GETList segments <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>
      • GETGet segment <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>
      • PUTRecalculate segment <Badge intent="info" minimal outlined>OAuth Scope: segments:write</Badge>
      • GETList segment subscribers <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>
      • GETList segment subscriber IDs <Badge intent="info" minimal outlined>OAuth Scope: segments:read</Badge>
      • DELDelete segment <Badge intent="info" minimal outlined>OAuth Scope: segments:write</Badge>
LogoLogo
LoginStart trialGet a demo
API ReferenceSegments

Create segment

POST
https://api.beehiiv.com/v2/publications/:publicationId/segments
POST
/v2/publications/:publicationId/segments
$curl -X POST https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/segments \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "name": "My Segment",
>  "input": {
>    "type": "subscriptions",
>    "subscriptions": [
>      "sub_00000000-0000-0000-0000-000000000000",
>      "sub_00000000-1111-1111-1111-111111111111"
>    ]
>  }
>}'
1{
2  "data": {
3    "id": "seg_00000000-0000-0000-0000-000000000000",
4    "name": "My Segment",
5    "type": "manual",
6    "total_results": 2,
7    "status": "completed",
8    "active": true,
9    "last_calculated": 1666800076
10  }
11}
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.
Was this page helpful?
Previous

List segments OAuth Scope: segments:read

Next
Built with

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.

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