Read and update case details with a hub key

This page covers reading and changing one case's details with a hub key. Paths are under https://prd-api-app.caseactive.com/v1/<hub id>/<case id>.

Calls

What a hub key may read and change follows the role of your hub's Virtual AssistantVirtual Assistant An automated team member that posts welcome messages, check-ins and stage posts for the firm; its posts carry a Virtual Assistant badge., bots. It reads the case's standard details by default, and can change none of them until an Admin allows it.

Letting the key change details

In Settings › Roles, edit the bots role and, under Case, tick Update all case fields specified in the role and the details the key may change: Title, Description, Date Opened, Status, Stage or custom fields. To let it read a custom field, tick it under Read all case fields specified in the role. See Change what a role can do.

GET /whoami answers the key's role on this case, with case_read_fields and case_write_fields, the details it may read and change. case_write_fields is left out while it may change none. A custom field shows there as meta_data.<field key>. It also answers case_modules, the sections the case shows: your hub's sections less any hidden on this case. A call on a section missing from it is refused.

Reading a case

curl https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "case_id": "cc-1a2b3c4d5e6f70",
    "host_id": "ca-7e6d5c4b3a2f10",
    "ref_id": "rear-end-2026",
    "title": "Jane Sample auto accident",
    "description": "Rear-end collision on Route 9. Waiting on the insurer's estimate.",
    "case_type": "general",
    "case_status": 1,
    "case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
    "date_opened": "2026-03-05",
    "meta_data": {
      "schema": [{"schema": {"type": "object", "properties": {"policy_number": {"type": "string", "title": "Policy number"}}}}],
      "content": [{"policy_number": "PN-5521"}]
    },
    "selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case"
  }
}

• By default the key reads case_id, ref_id (the Tag IDTag ID A permanent label you give a case, such as rear-end-2026, also shown as Reference ID and used in imports.), case_status, date_opened, title, description, case_type and case_stage. A detail the case doesn't have is left out.
• case_stage is a 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.'s ID; GET /v1/<hub id>/stages lists their names.
• meta_data.content holds the custom field values, one object per field page, by field key, but only the fields the key may read. By default it reads none, so the first page comes back empty; in the example an Admin has let it read Policy number. meta_data.schema describes each page's fields.
• hidden_modules lists the sections hidden on this case, when there are any.

Changing a case

PUT /case takes any of these fields as JSON, and changes only the ones you send.

curl -X PUT https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/case \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"case_stage": "stage::20260927120000_8c1f0e2d3b4a59", "meta_data": [{"policy_number": "PN-5521"}]}'

It answers 200 with the case's ID. If any field you send isn't one the key may change, and its value differs from the case's, the whole call is refused with 403 and changes nothing; reason names the fields, a custom one as meta_data.<field key>. A field sent with the value the case already holds isn't a change, so it's neither refused nor written, and a call that changes nothing answers 204.

• Moving an open case into a stage adds that stage's milestone post, as the Virtual Assistant, if your hub has one; see Add a post automatically when a case reaches a stage. Nothing else is posted or sent: closing a case or changing its details tells nobody.
• Once a case is closed, every change through a hub key is refused, reopening included. Reopen it in the Admin Panel or with a manage key; see Close or reopen a case.
• The Tag ID and case type can't be changed here; a manage key can change the type.

The team

GET /team lists everyone on the case, the Virtual Assistant and disabled members included, all at once. A case holds 20 at most, the Virtual Assistant counted.

{
  "data": {
    "items": [
      {
        "case_id": "cc-1a2b3c4d5e6f70",
        "user_id": "cu-4f1c2a9e8b7d60",
        "case_role_id": "role::clients",
        "case_designation": "primary",
        "case_notify": 1,
        "host_user_status": 1,
        "given_name": "Jane",
        "family_name": "Sample",
        "locale": "en",
        "zoneinfo": "America/New_York"
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/team"
  }
}

• case_role_id is the person's role on this case, and case_designation their designationDesignation A label for someone's job on a case, such as Lead Attorney, Paralegal or Guardian., such as primary.
• host_user_status is 0 for someone disabled in your hub.
• Each person's names, language (locale) and time zone (zoneinfo) come back by default. Email addresses and phone numbers never do.
• A hub key can't add or remove people: those calls answer 403 HostAddCaseUserNotEnabledException and HostRemoveCaseUserNotEnabledException. Use a manage key; see Add and remove case members with a manage key.

Template values

GET /placeholders answers, under placeholders, the value each code in your templates fills in on this case, such as clients.primary.full_name, clients.primary.email, case_ref_id and company.phone. A code for a designation nobody on the case holds is left out. With the Team section switched off or hidden on the case, every team code is left out and the rest still come back. See Prefill form fields with case details.

If a call is refused

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