Segments

Overview

Named groups of contacts, used as broadcast audiences and as automation conditions. Membership can be managed explicitly through the API, which is how you keep a segment in step with a list that lives in your own system.

5 endpoints. Requires contacts.view or contacts.edit on the token.

Method	Path	What it does
GET	/segments	List segments
POST	/segments	Create a segment
DELETE	/segments/{id}	Delete a segment
GET	/segments/{id}	Get segment details
PUT	/segments/{id}/members	Add or remove segment members

Endpoints

GET /segments

List segments

List all contact segments. Requires `contacts.view` permission.

Requires the contacts.view permission.

Example

curl -X GET "https://orqestra.id/api/v2/segments" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403. Try it in the playground →

---

POST /segments

Create a segment

Create a new contact segment. Name must be unique per organization. Requires `contacts.edit` permission.

Requires the contacts.edit permission.

Request body

Field	Type	Required	Description
name	string	required	Segment name (unique per organization)
description	string	optional	Segment description
isDynamic	boolean	optional	Resolve membership from rules Defaults to false.
rules	object | object	optional	Dynamic segment rules

Example

curl -X POST "https://orqestra.id/api/v2/segments" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'

Responds with 200 · 400 · 401 · 403 · 409. Try it in the playground →

---

DELETE /segments/{id}

Delete a segment

Delete a contact segment. Contact associations are removed but contacts themselves are not deleted. Requires `contacts.edit` permission.

Requires the contacts.edit permission.

Parameter	In	Type	Required	Description
id	path	string	required	Segment ID (cuid)

Example

curl -X DELETE "https://orqestra.id/api/v2/segments/$id" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403 · 404. Try it in the playground →

---

GET /segments/{id}

Get segment details

Get segment details with paginated member contacts. Requires `contacts.view` permission.

Requires the contacts.view permission.

Parameter	In	Type	Required	Description
id	path	string	required	Segment ID (cuid)
page	query	integer	optional	Page number Defaults to 1.
limit	query	integer	optional	Contacts per page (max 200) Defaults to 50.

Example

curl -X GET "https://orqestra.id/api/v2/segments/$id" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403 · 404. Try it in the playground →

---

PUT /segments/{id}/members

Add or remove segment members

Add or remove contacts from a segment. All contactIds must belong to the organization. Requires `contacts.edit` permission.

Requires the contacts.edit permission.

Parameter	In	Type	Required	Description
id	path	string	required	Segment ID (cuid)

Request body

Field	Type	Required	Description
action	add · remove	required	Whether to add or remove contacts
contactIds	array of string	required	Array of contact IDs

Example

curl -X PUT "https://orqestra.id/api/v2/segments/$id/members" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "contactIds": [
      "string"
    ]
  }'

Responds with 200 · 400 · 401 · 403 · 404. Try it in the playground →