Skip to content

Cases ​

The case-management view of your conversations — the same rows, filters and ordering the Cases page in your workspace shows.

OperationEndpointScope
List casesGET /api/v1/casesconversations:read

A case is a conversation ​

Every row carries the conversation id, so you can list cases here and pull the full transcript from GET /api/v1/conversations/{id}/events without holding two identifiers for one thing.

Where GET /api/v1/conversations returns the plain record, this returns the case-management row: who the customer is (customer_id, customer_name, customer_email, customer_phone), which agent took it, how it turned out, the last_message, the message_count, and created_at / updated_at.

bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/cases?status=active&page=1&page_size=20" \
  -H "Authorization: Bearer sk_…"

Two kinds of status, and they are not the same thing ​

FieldMeaning
statusThe ticket lifecycle — active, ended, resolved, escalated, abandoned
sentiment_labelThe AI verdict on how the customer felt
resolved / resolution_reasonWhether the AI considers the issue settled, and why
needs_followupFlagged for a human to pick up
qa_scoresScorecard: resolution, compliance, sentiment, response, tools, overall

A conversation can be ended without being resolved. The lifecycle is what happened to the ticket; the rest is the AI's judgement about it.

Who handled it ​

workflow_id and workflow_name identify the agent. Two absences mean different things:

  • no workflow_id at all — no agent matched the inbound
  • workflow_name: null — an agent did handle it, and was deleted afterwards

Search, filters, date range ​

ParameterValues
qFree text over the customer's name, email and phone, the details your site passed about the visitor, the case id — and what was said in the conversation (see below)
statusactive, ended, resolved, escalated, abandoned
channelThe channel the case started on, e.g. web, whatsapp, phone
originatorWho spoke first: customer, agent (a greeting or a dial-out) or system
needs_followuptrue to list only cases flagged for a human
customer_idOnly this customer's cases
created_after / created_beforeISO dates bounding when the case was opened
sort_byupdated_at (default), created_at, status, channel_started
sort_orderdesc (default) or asc

By default the most recently active case comes first, so an old case that just received a message is at the top — the same order as the Cases page.

All filters are applied before paging, so totals and page counts stay correct as you scroll.

Searching what was said ​

q also matches the message text of a conversation's turns — what the customer, the AI and your team said, never tool payloads. So q=refund 4417 finds the case where someone mentioned a refund on order 4417.

  • The query is split on spaces into at most 8 terms. A message matches when it contains all of them.
  • Punctuation at the start or end of a term is ignored (4417, finds 4417.); a term longer than 64 characters is dropped.
  • Message text contributes at most the 500 newest-matching conversations to the result.
  • The API row does not include the matching excerpt — the Cases and Conversations pages show it.

last_message and message_count leave out any turn the AI produced while muted, when a person held the call.

Paging reports a total ​

json
{
  "data": [ … ],
  "pagination": { "page": 1, "page_size": 20, "total": 347, "total_pages": 18 }
}

page (default 1) and page_size (default 20, up to 100). This differs from the call log, which pages by cursor — a cursor suits an endless scroll but cannot tell you how many rows matched, and a table needs to say "20 of 347".