Create and update cases with a manage key

This page covers the case calls a manage key can make. Paths are under https://prd-api-manage.caseactive.com/v1/<hub id>.

Calls

Listing cases

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

{
  "data": {
    "items": [
      {
        "case_id": "cc-1a2b3c4d5e6f70",
        "host_id": "ca-7e6d5c4b3a2f10",
        "ref_id": "rear-end-2026",
        "title": "Jane Sample auto accident",
        "case_type": "general",
        "case_status": 1,
        "case_stage": "stage::20260927120000_8c1f0e2d3b4a59",
        "users": {
          "cu-7e6d5c4b3a2f10": "role::bots",
          "cu-4f1c2a9e8b7d60": "role::clients",
          "cu-9d8c7b6a5f4e30": "role::staff"
        },
        "created_on": "2026-10-02T14:05:09+00:00"
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases?type=1"
  }
}

• users 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.. It includes 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., as role::bots.
• 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. To find a case by its Tag IDTag ID A permanent label you give a case, such as rear-end-2026, also shown as Reference ID and used in imports., see Search cases and users with a manage key.

Case fields

POST /cases and PUT /cases/<case_id> take these fields as JSON. Fields not listed are ignored.

You can't add people on create; only the Virtual Assistant is put on a new case. Add them next with POST /cases/permissions; see Add and remove case members with a manage key.

Creating a case

curl -X POST https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref_id": "rear-end-2026", "title": "Jane Sample auto accident", "case_type": "general", "date_opened": "2026-10-02"}'

It answers 201 with the new case's ID:

{"data": {"case_id": "cc-1a2b3c4d5e6f70", "selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases"}}

Nobody is emailed. Your Assign Cases rules for every case, and for the case's type, put their people on it, so adding one of them yourself afterwards is refused as a duplicate. A case created at a stage gets no milestone post.

Reading a case

GET /cases/<case_id> answers the case's case_id, host_id, ref_id, title, description, case_type, case_status, case_stage, date_opened, hidden_modules, meta_data, users_ct (how many people are on it, the Virtual Assistant included), created_on and updated_on. To see who's on it, use GET /cases/permissions?case_id=<case_id>.

Changing a case

PUT /cases/<case_id> takes any of the case fields but ref_id, and changes only the ones you send. It answers 204 with no body.

• Moving an open case into a stage adds that stage's milestone post, as the Virtual Assistant, if your hub has one for it; see Add a post automatically when a case reaches a stage. Nothing else is posted or sent: closing a case or changing its type tells nobody.
• meta_data replaces every custom field the case has.
• A closed case can still be changed, so a sync can reopen it with "case_status": 1.

Stages and custom fields

GET /stages lists your hub's stages, which an Admin sets up under Settings › Stages, in order, with each one's stage_id, name, description and order, all at once. A key can read stages but not change them.

GET /schemas?schema_type=cases answers your hub's case custom fields, set under Settings › Fields, as a list of pages, each with its fields' keys, labels and types. Send meta_data as a list with one object per page, in the same order, each holding values by field key:

{"meta_data": [{"policy_number": "PN-5521", "insurer": "Northwind Mutual"}]}

A value must suit its field's type, or the call is refused. Required is checked only by the case forms in the Admin Panel and the Lobby, so a case you create or update here can leave a required field empty.

Deleting a case

DELETE /cases/<case_id> answers 204. The case leaves your lists at once and is then deleted for good, with its posts, files, forms, e-signs, invoices, events, tasks and notes. It can't be undone, and nobody is told. Its Tag ID is free again once the deletion has finished.

If a call is refused

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