Segment API

Create and manage dynamic contact segments to send targeted messages and automate tasks.

Authentication: All requests require an x-api-key header. Response: Successful requests return [200 OK] with the appropriate schema.

Endpoints

1. List/Search Segments

GET /v1/segments

Retrieve a list of available segments with optional filtering and search.

Query Parameters:

• workspaceId (string, optional) – Filter by workspace ID

• limit (string, optional) – Maximum number of results

• page (string, optional) – Page number for pagination

• searchText (string, optional) – Free text search

Response: [200 OK] – Array of Segment

2. Create a Segment

POST /v1/segments

Create a new dynamic segment.

Request Body: Segment (application/json) Response: [200 OK] – Segment

3. Get Segment by ID

GET /v1/segments/{segmentId}

Retrieve details of a specific segment by ID.

Path Parameters:

• segmentId (string, required) – Unique segment ID

Response: [200 OK] – Segment

4. Delete Segment by ID

DELETE /v1/segments/{segmentId}

Delete a specific segment by ID.

Path Parameters:

• segmentId (string, required) – Unique segment ID

Response: [200 OK] – DeleteResponse

Schemas

Segment Schema

{
  "id": "string",
  "name": "string",
  "type": "string",
  "status": "string",
  "segments": [
    { "id": "string" }
  ],
  "retargetBroadcast": {
    "id": "string"
  },
  "retargetEngagementType": "string",
  "scheduleDateTime": "string",
  "startedAt": "string",
  "completedAt": "string"
}

SegmentsResponse Schema

[
  {
    "id": "seg_12345",
    "name": "High Value Customers",
    "type": "dynamic",
    "status": "active",
    "segments": [],
    "retargetBroadcast": { "id": "brd_67890" },
    "retargetEngagementType": "click",
    "scheduleDateTime": "2025-09-05T09:00:00Z",
    "startedAt": "2025-09-05T09:05:00Z",
    "completedAt": null
  }
]

DeleteResponse Schema

{
  "success": true
}