> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hive.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hive.co/_mcp/server.

# Segments

Segments are groups of contacts in Hive. Through the API you can list and create segments, delete them, and read or change the users in **static** segments. Adding users to a segment can trigger segment-based automations configured in Hive.

## Endpoints

| Method and path                             | Scope            | Response            |
| ------------------------------------------- | ---------------- | ------------------- |
| `GET /segments/`                            | `segments:read`  | `200 OK`            |
| `POST /segments/`                           | `segments:write` | `201 Created`       |
| `DELETE /segments/{segment_id}/`            | `segments:write` | `204 No Content`    |
| `GET /segments/{segment_id}/users/`         | `segments:read`  | `200 OK`, paginated |
| `POST /segments/{segment_id}/users/`        | `segments:write` | `202 Accepted`      |
| `POST /segments/{segment_id}/users/remove/` | `segments:write` | `202 Accepted`      |

## The segment object

```json
{
    "id": "6603a1f2c9e77a0012ab34cd",
    "name": "VIP Fans",
    "description": "Customers with premium purchase history",
    "time_created": "2026-03-20T10:30:00-04:00"
}
```

| Field          | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `id`           | Hive segment ID, an opaque string                                       |
| `name`         | Segment name                                                            |
| `description`  | Segment description, or `null` when unset                               |
| `time_created` | ISO 8601 timestamp with UTC offset when the segment was created in Hive |

`GET /segments/` returns the brand's segments in a `segments` array.

Whether a segment is static or dynamic isn't exposed by the API. Endpoints that require a static segment return `422 Unprocessable Entity` for a dynamic one.

## Create a segment

```json
{
    "name": "VIP Fans",
    "description": "Customers with premium purchase history"
}
```

* `name` (required): segment name.
* `description` (optional): segment description. Omit it rather than sending `null`.

> **Duplicate names**
>
> Segment names must be unique within the brand. If a segment with the same name already exists,
> Hive returns `409 Conflict`.

## Delete a segment

Only static segments can be deleted. If the segment can't be deleted, Hive returns `422 Unprocessable Entity`. If the segment doesn't exist, Hive returns `404 Not Found`. A failure while deleting returns `500 Internal Server Error`.

## List segment users

`GET /segments/{segment_id}/users/` accepts `limit` (`0`–`500`, default `500`) and `offset` (default `0`). Users are returned in the order they were added to the segment, oldest first. An out-of-range `limit` or `offset` returns `422 Unprocessable Entity`, and an unknown segment returns `404 Not Found`.

```json
{
    "offset": 0,
    "limit": 100,
    "total_items": 2,
    "items": [
        { "email": "jamie@example.com", "phone": "+15195551234" },
        { "email": "morgan@example.com" }
    ]
}
```

| Field           | Description                          |
| --------------- | ------------------------------------ |
| `offset`        | Current pagination offset            |
| `limit`         | Current page size                    |
| `total_items`   | Total number of users in the segment |
| `items[].email` | User email, if available             |
| `items[].phone` | User phone number, if available      |

## Add or remove users

`POST /segments/{segment_id}/users/` adds users and `POST /segments/{segment_id}/users/remove/` removes them. Both take the same body:

```json
{
    "users": [
        { "email": "jamie@example.com", "phone": "+15195551234" },
        { "email": "morgan@example.com" }
    ]
}
```

* `users` (required): 1–50 users per request.
* Each user needs an `email` or a `phone`. `email` must be a valid email address and `phone` must not be blank. Omit a field rather than sending `null`.
* Users are matched to existing contacts by email or phone only.

Both endpoints are asynchronous and return `202 Accepted`. An unknown segment returns `404 Not Found`.

> **Warning**
>
> Only **static segments** can be modified through the API. Adding or removing users on a
> non-static segment returns `422 Unprocessable Entity`.

## Errors

Error responses for unknown segments, duplicate names, failed deletes, and non-static segments use the shape `{"errors": ["..."]}`, for example `{"errors": ["Segment not found."]}`.