Overview
Segments group users and companies for targeted feature rollouts. Use segments to beta-test features with specific customers, enable internal testing, or create VIP access lists.
Base URL
/api/platform/segmentsNOTE
These endpoints require authentication with a Super Admin account.
Endpoints
List Segments
GET /api/platform/segmentsResponse 200 OK
[
{
"id": "clx1234...",
"name": "beta-testers",
"description": "Early access customers",
"isActive": true,
"userIds": ["user-123", "user-456"],
"companyIds": ["company-789"],
"updatedAt": "2025-12-01T00:00:00.000Z"
}
]Get Segment
GET /api/platform/segments/:idParameters
| Name | Type | Description |
|---|---|---|
id | string | Segment ID |
Response 200 OK - Full segment object
Response 404 Not Found - Segment not found
Create Segment
POST /api/platform/segmentsRequest Body
{
"name": "internal-team",
"description": "Internal development and QA team",
"userIds": ["user-123"],
"companyIds": [],
"isActive": true
}| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✅ | Unique segment name |
description | string | ❌ | Human-readable description |
userIds | string[] | ❌ | User IDs to include (default: []) |
companyIds | string[] | ❌ | Company IDs to include (default: []) |
isActive | boolean | ❌ | Whether segment is active (default: true) |
Response 201 Created
{
"id": "clx1234...",
"name": "internal-team"
}Update Segment
PUT /api/platform/segments/:idRequest Body - All fields optional
{
"name": "updated-name",
"description": "Updated description",
"userIds": ["user-123", "user-456"],
"companyIds": ["company-789"],
"isActive": false
}Response 200 OK - Updated segment object
Response 404 Not Found - Segment not found
Delete Segment
DELETE /api/platform/segments/:idResponse 200 OK
{
"success": true
}WARNING
Deleting a segment also removes all feature flag associations (cascading delete).
Helper Endpoints
These endpoints support the UI's multi-select components for adding users/companies to segments.
Search Companies
GET /api/platform/segments/search-companies?q=tech&limit=50Query Parameters
| Name | Type | Default | Description |
|---|---|---|---|
q | string | - | Search query (searches name and ID) |
limit | number | 50 | Max results to return |
Response 200 OK
[
{
"id": "company-123",
"label": "TechFlow MSP",
"description": "professional plan"
}
]Search Users
GET /api/platform/segments/search-users?q=john&limit=50Query Parameters
| Name | Type | Default | Description |
|---|---|---|---|
q | string | - | Search query (searches email, name, ID) |
limit | number | 50 | Max results to return |
Response 200 OK
[
{
"id": "user-123",
"label": "john@example.com",
"description": "John Smith"
}
]Resolve Company IDs
POST /api/platform/segments/resolve-companiesRequest Body
{
"ids": ["company-123", "company-456"]
}Response 200 OK - Array of { id, label, description } objects
Resolve User IDs
POST /api/platform/segments/resolve-usersRequest Body
{
"ids": ["user-123", "user-456"]
}Response 200 OK - Array of { id, label, description } objects