Add and remove case members with a manage key

This page covers the calls that put people on cases and take them off. Paths are under https://prd-api-manage.caseactive.com/v1/<hub id>, and the person must already be in your hub; see Add and update users with a manage key.

Calls

There's no call to change someone's role on a case, or to send their invitation again: take them off and add them again, which runs your welcome rules for their role.

Adding someone

A designationDesignation A label for someone's job on a case, such as Lead Attorney, Paralegal or Guardian. says who someone is on the case, so templates can name, for example, the case's primary client. role::clients keeps client_designation, and every other role keeps staff_designation. Leave the other one out, or send primary: a guardian with any other role, or a staff designation with role::clients, is refused at its field, and nobody is added.

curl -X POST https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/permissions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"case_id": "cc-1a2b3c4d5e6f70", "user_id": "cu-4f1c2a9e8b7d60", "case_role_id": "role::clients", "case_notify": true, "client_designation": "primary"}'

It answers 201 with the case_id and user_id.

• A case holds 20 people, its 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. included, so 19 others.
• A closed case takes nobody. Reopen it first; see Create and update cases with a manage key.
• The person sees the case in their portal at once.

What happens next

• With case_notify set to true, the person gets an invitation to the case from your firm, with a link that signs them in to it. It goes to their confirmed email address, or as a text to their confirmed phone number if they have no email; with neither, nothing is sent. Someone who has removed your firm's access gets nothing.
• Your welcome rules for their role add their templates to the case; see Welcome clients when they join a case.
• Nothing is posted on the case, and no webhook is sent.

Changing a designation

PUT /cases/permissions/<case_id>/<user_id> with {"case_designation": "lead_attorney"} answers 204. It changes the person's designation on that case and nothing else: they stay on everything they're on, nobody is sent anything, and no welcome rule runs. The next template post and prefilled form use the new one.

The designation must suit their role on the case: primary or guardian for role::clients, and the six staff designations for any other role. The Virtual Assistant's can't be changed.

curl -X PUT https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/permissions/cc-1a2b3c4d5e6f70/cu-9d8c7b6a5f4e30 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"case_designation": "lead_attorney"}'

Reading who's on a case

GET /cases/permissions?case_id=cc-1a2b3c4d5e6f70 answers everyone on the case at once, the Virtual Assistant included, as role::bots:

{
  "data": {
    "items": [
      {
        "case_id": "cc-1a2b3c4d5e6f70",
        "user_id": "cu-4f1c2a9e8b7d60",
        "case_role_id": "role::clients",
        "case_designation": "primary",
        "case_notify": true,
        "case_status": 1,
        "case_ref_id": "ca-7e6d5c4b3a2f10::rear-end-2026",
        "given_name": "Jane",
        "family_name": "Sample",
        "host_user_status": 1,
        "locale": "en",
        "zoneinfo": "US/Eastern",
        "created_on": "2026-10-02T14:06:30+00:00"
      }
    ],
    "currentItemCount": 1,
    "selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases/permissions?case_id=cc-1a2b3c4d5e6f70"
  }
}

Each entry also carries a copy of the case's title and description. Email addresses and phone numbers aren't included: read the person with GET /users/relations/<user_id>. A case that isn't in your hub answers an empty list.

Taking someone off

DELETE /cases/permissions/<case_id>/<user_id> answers 204, also when the person wasn't on the case, so it's safe to repeat. Nobody is told, though the person is sent a cancellation for each upcoming event on the case, answered or not. The person loses the case from their portal at once. The Virtual Assistant can't be taken off.

If a call is refused

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