Segments API

The Segments API allows you to list your segments that you defined in your channel, as well as query specific segments for a list of subscribers that belong within that segment.

This API endpoint is not for modifying or creating segments themselves. This must be done within Broadcast’s user interface.

Required Permissions

All endpoints require authentication via an API token with appropriate permissions:

• List and read segments (Read)

Segment Object

Field	Description
`id`	Unique identifier of the segment
`name`	Name of the segment
`description`	Description of the segment
`created_at`	When the segment was created

Endpoints

List Segments

GET /api/v1/segments.json?page=1

Returns a paginated list of segments that belong to a channel (as determined by your access token).

Parameters

• page: Optional parameter for the page number to return (default is 1)

Response

{
  "segments": [
    {
      "id": 1,
      "name": "Active Subscribers",
      "description": "Subscribers who have opened at least one email in the last 30 days.",
      "created_at": "2024-06-01T12:34:56Z"
    }
  ]
}

List Subscribers in a Segment

GET /api/v1/segments/1.json?page=1

Returns a paginated list of subscribers in a specific segment (of up to 250 subscribers per page).

Parameters

• page: Optional parameter for the page number to return (default is 1)

Response

{
  "segment": {
    "id": 1,
    "name": "Active Subscribers",
    "description": "Subscribers who have opened at least one email in the last 30 days.",
    "created_at": "2024-06-01T12:34:56Z"
  },
  "subscribers": [
    {
      "id": "123",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "ip_address": "192.168.1.1",
      "is_active": true,
      "source": "web_form",
      "subscribed_at": "2024-03-20T10:00:00Z",
      "unsubscribed_at": null,
      "created_at": "2024-03-20T10:00:00Z",
      "tags": ["newsletter", "product-updates"]
    }
  ]
}