Access the beehiiv API with managed OAuth authentication. Manage newsletter publications, subscriptions, posts, custom fields, segments, tiers, and automations.
All beehiiv API endpoints follow this pattern:
/beehiiv/v2/{resource}Reference
List Publications
GET /beehiiv/v2/publicationsQuery Parameters:
| Parameter | Description |
|---|---|
limit | Results per page (1-100, default: 10) |
page | Page number (default: 1) |
expand[] | Expand with: stats, stat_active_subscriptions, stat_average_open_rate, etc. |
order_by | Sort by: created or name |
direction | Sort direction: asc or desc |
Response:
{
"data": [
{
"id": "pub_c6c521e4-91ac-4c14-8a52-06987b7e32f2",
"name": "My Newsletter",
"organization_name": "My Organization",
"referral_program_enabled": true,
"created": 1770767522
}
],
"page": 1,
"limit": 10,
"total_results": 1,
"total_pages": 1
}Get Publication
GET /beehiiv/v2/publications/{publication_id}List Subscriptions
GET /beehiiv/v2/publications/{publication_id}/subscriptionsQuery Parameters:
| Parameter | Description |
|---|---|
limit | Results per page (1-100, default: 10) |
cursor | Cursor for pagination (recommended) |
page | Page number (deprecated, max 100 pages) |
email | Filter by exact email (case-insensitive) |
status | Filter: validating, invalid, pending, active, inactive, all |
tier | Filter: free, premium, all |
expand[] | Expand with: stats, custom_fields, referrals |
order_by | Sort field (default: created) |
direction | Sort direction: asc or desc |
Response:
{
"data": [
{
"id": "sub_c27d9640-f418-43a8-a0f9-528c20a05002",
"email": "subscriber@example.com",
"status": "active",
"created": 1770767524,
"subscription_tier": "free",
"subscription_premium_tier_names": [],
"utm_source": "direct",
"utm_medium": "",
"utm_channel": "website",
"utm_campaign": "",
"referring_site": "",
"referral_code": "gBZbSVal1X",
"stripe_customer_id": ""
}
],
"limit": 10,
"has_more": false,
"next_cursor": null
}Get Subscription by ID
GET /beehiiv/v2/publications/{publication_id}/subscriptions/{subscription_id}Query Parameters:
| Parameter | Description |
|---|---|
expand[] | Expand with: stats, custom_fields, referrals, tags |
Get Subscription by Email
GET /beehiiv/v2/publications/{publication_id}/subscriptions/by_email/{email}Create Subscription
POST /beehiiv/v2/publications/{publication_id}/subscriptions
Content-Type: application/json
{
"email": "newsubscriber@example.com",
"utm_source": "api",
"send_welcome_email": false,
"reactivate_existing": false
}Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Subscriber email address |
reactivate_existing | boolean | No | Reactivate if previously unsubscribed |
send_welcome_email | boolean | No | Send welcome email |
utm_source | string | No | UTM source for tracking |
utm_medium | string | No | UTM medium |
referring_site | string | No | Referral code of referring subscriber |
custom_fields | object | No | Custom field values (fields must exist) |
double_opt_override | string | No | on or off to override double opt-in |
tier | string | No | Subscription tier |
premium_tier_names | array | No | Premium tier names to assign |
Update Subscription
PATCH /beehiiv/v2/publications/{publication_id}/subscriptions/{subscription_id}
Content-Type: application/json
{
"utm_source": "updated-source",
"custom_fields": [
{"name": "First Name", "value": "John"}
]
}Delete Subscription
DELETE /beehiiv/v2/publications/{publication_id}/subscriptions/{subscription_id}List Posts
GET /beehiiv/v2/publications/{publication_id}/postsQuery Parameters:
| Parameter | Description |
|---|---|
limit | Results per page (1-100, default: 10) |
page | Page number |
status | Filter by status |
expand[] | Expand with additional data |
Response:
{
"data": [],
"page": 1,
"limit": 10,
"total_results": 0,
"total_pages": 0
}Get Post
GET /beehiiv/v2/publications/{publication_id}/posts/{post_id}Delete Post
DELETE /beehiiv/v2/publications/{publication_id}/posts/{post_id}List Custom Fields
GET /beehiiv/v2/publications/{publication_id}/custom_fieldsResponse:
{
"data": [
{
"id": "95c9653f-a1cf-45f0-a140-97feef19057b",
"kind": "string",
"display": "Last Name",
"created": 1770767523
},
{
"id": "4cfe081e-c89b-4da5-9c1a-52a4fb8ba69e",
"kind": "string",
"display": "First Name",
"created": 1770767523
}
],
"page": 1,
"limit": 10,
"total_results": 2,
"total_pages": 1
}Field Kinds: string, integer, boolean, date, datetime, list, double
Create Custom Field
POST /beehiiv/v2/publications/{publication_id}/custom_fields
Content-Type: application/json
{
"display": "Company",
"kind": "string"
}Update Custom Field
PATCH /beehiiv/v2/publications/{publication_id}/custom_fields/{custom_field_id}
Content-Type: application/json
{
"display": "Company Name"
}Delete Custom Field
DELETE /beehiiv/v2/publications/{publication_id}/custom_fields/{custom_field_id}List Segments
GET /beehiiv/v2/publications/{publication_id}/segmentsResponse:
{
"data": [],
"page": 1,
"limit": 10,
"total_results": 0,
"total_pages": 0
}Get Segment
GET /beehiiv/v2/publications/{publication_id}/segments/{segment_id}Delete Segment
DELETE /beehiiv/v2/publications/{publication_id}/segments/{segment_id}List Tiers
GET /beehiiv/v2/publications/{publication_id}/tiersGet Tier
GET /beehiiv/v2/publications/{publication_id}/tiers/{tier_id}Create Tier
POST /beehiiv/v2/publications/{publication_id}/tiers
Content-Type: application/json
{
"name": "Premium",
"description": "Premium tier with exclusive content"
}Update Tier
PATCH /beehiiv/v2/publications/{publication_id}/tiers/{tier_id}
Content-Type: application/json
{
"name": "Updated Tier Name"
}List Automations
GET /beehiiv/v2/publications/{publication_id}/automationsGet Automation
GET /beehiiv/v2/publications/{publication_id}/automations/{automation_id}Get Referral Program
GET /beehiiv/v2/publications/{publication_id}/referral_program