Skip to main content

Segments

Named groupings of calls, scoped to a project. A call can carry several — segments are many-to-many, not a single category — which is what lets the same call count toward "winback" and "north" at once.

List segments​

GET /api/segments

{
  "segments": [
    {
      "uuid": "sg1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
      "name": "winback",
      "call_count": 142,
      "created_at": "2026-08-02T10:00:00Z",
      "updated_at": "2026-09-18T11:02:10Z"
    }
  ]
}

Create a segment​

POST /api/segments

{ "name": "winback" }

Segments are also created on demand by CSV upload when a segments column names one that does not exist yet.

Rename a segment​

PATCH /api/segments/{uuid}

{ "name": "winback-q4" }

Renaming keeps every call attached — the segment's identity is its UUID, not its name.

Delete a segment​

DELETE /api/segments/{uuid} → 204

Removes the grouping. The calls themselves are untouched; they simply lose this segment and may become unassigned.

Assign segments to calls​

Replace one call's segments​

PUT /api/calls/{id}/segments

{ "segment_uuids": ["sg1a2b3c-…", "sg4d5e6f-…"] }

Replaces, not appends. Send the full set you want; an empty array clears them.

Add to many calls at once​

POST /api/calls/bulk-segments

{
  "call_ids": [1042, 1043, 1044],
  "segment_uuids": ["sg1a2b3c-…"]
}

Adds, rather than replacing — existing segments on those calls are kept. This is the route to use after reviewing a filtered list and deciding the whole page belongs together.

Filtering by segment​

Most list and reporting endpoints take segment_uuids, comma-separated and OR-matched — a call in any of the named segments is included:

GET /api/calls?segment_uuids=sg1a2b3c-…,sg4d5e6f-…
GET /api/dashboard?segment_uuids=sg1a2b3c-…

An unknown UUID returns 400 rather than an empty page, so a typo is visible instead of looking like "no calls matched".

To find calls that were never sorted:

GET /api/calls?unassigned=1

Customer segments​

Customers carry a segment field of their own, separate from call segments. Assign it in bulk with:

POST /api/customers/bulk-segment

The two are worth keeping distinct: a customer segment describes who someone is ("enterprise", "smb"), while a call segment describes what a conversation was part of ("q4-winback", "post-launch-support"). The same customer's calls can belong to different call segments over time.