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

The segment object

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

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

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

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

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.

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

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:

{
    "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.

Errors

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