Find cases with a hub key

This page covers the calls a hub key uses to find cases. Paths are under https://prd-api-app.caseactive.com/v1/<hub id>.

Calls

A hub key acts as your hub's Virtual AssistantVirtual Assistant An automated team member that posts welcome messages, check-ins and stage updates for the firm; its posts carry a Virtual Assistant badge., which is on every case, so these calls reach every case in your hub, the two sample cases included.

A hub key can't create a case: POST /cases answers 403 HostCreateCaseNotEnabledException. To create cases from your software, use a manage key; see Create and update cases with a manage key.

Listing cases

curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?status=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "items": [
      {
        "case_id": "cc-1a2b3c4d5e6f70",
        "case_ref_id": "ca-7e6d5c4b3a2f10::rear-end-2026",
        "title": "Jane Sample auto accident",
        "team": {
          "cu-7e6d5c4b3a2f10": "role::bots",
          "cu-4f1c2a9e8b7d60": "role::clients",
          "cu-9d8c7b6a5f4e30": "role::staff"
        }
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?status=1"
  }
}

• Cases come in Tag IDTag ID A permanent label you give a case, such as rear-end-2026, also shown as Reference ID and used in imports. order, from Z to A, not by date.
• case_ref_id is your hub's ID, two colons and the case's Tag ID.
• team maps each person on the case to their roleRole A set of permissions that decides what someone can see and do on a case, such as staff or clients., with no names. For names, read the case's team; see Read and update case details with a hub key.
• While more cases remain, the page also holds nextLink, the next page's full address, and startKey. Call nextLink, or send startKey as start_key, until a page comes back without them.
• Cases being deleted are left out, so a page can hold fewer than limit cases while more remain. Go by nextLink, not the count.
• A case's title and status here can lag a change by a few seconds.

Searching cases

GET /cases/search matches your words anywhere in a case's Tag ID, and from the start of a word in its title, and allows small typos. It doesn't search descriptions.

curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/search?query=rear-end-2026" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "found": 1,
    "page": 1,
    "hits": [
      {
        "document": {
          "case_id": "cc-1a2b3c4d5e6f70",
          "ref_id": "rear-end-2026",
          "title": "Jane Sample auto accident",
          "case_status": 1,
          "case_type": "general",
          "case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
          "date_opened": 1772668800,
          "created_on": 1791043509,
          "last_activity": 1791050112,
          "users_ct": 3
        }
      }
    ],
    "selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/search?query=rear-end-2026"
  }
}

• Each hit's document holds the case's ID, bare Tag ID, title, status, case typeCase type A category for cases, such as general, used to aim automations at the right cases., stageStage A step a case moves through, such as Intake or Demand sent, which the firm names and describes and which shows on the case page., how many people are on it, and its dates as Unix seconds in UTC.
• found is how many cases match. Page through them with page; there's no nextLink.
• A case is searchable within seconds of a change.

Finding a case by its Tag ID

There's no exact lookup by Tag ID. Search for it, then keep the hit whose document.ref_id is exactly your Tag ID, since a search also finds close matches such as rear-end-2025. Search with status=1, then status=0, to cover open and closed cases.

Once you have the case's ID, every call about the case uses it; see Read and update case details with a hub key.

Your hub's settings

None of them pages: each answers everything at once.

If a call is refused

For the error body and the rest of the codes, see Handle API errors and status codes.