Add and update users with a manage key

This page covers the calls for the people in your hub. Paths are under https://prd-api-manage.caseactive.com/v1/<hub id>. A key adds people as Users and changes only whether they can sign in: it can't make anyone an Admin or a Manager, or change their details after adding them.

Calls

Listing people

Each person comes with user_id, given_name, family_name, email, phone, email_verified, phone_verified, locale, zoneinfo, host_user_type (admin, manage or user), host_user_status (1 active, 0 disabled), host_ref_id, host_default_role, host_staff_designation, host_cases_ct (their number of cases), host_granted_status (approve, or reject once they've removed your hub's access to their profile) and created_on. The list is in no particular order. It includes 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., whose host_user_type is bot, and the two sample people every new hub starts with. While more people remain, call nextLink, or send startKey as start_key.

Adding someone

curl -X POST https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/users/relations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "jane.sample@example.com", "given_name": "Jane", "family_name": "Sample", "zoneinfo": "America/New_York", "host_ref_id": "cl-1042"}'

It answers 201 with their user_id:

{"data": {"host_id": "ca-7e6d5c4b3a2f10", "user_id": "cu-4f1c2a9e8b7d60", "selfLink": "https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/users/relations"}}

• Everyone a key adds is a User, active, whatever you send.
• A key can't give anyone the portal's case powers: creating cases, adding people to cases or removing them. Sending host_create_case, host_add_case_user or host_remove_case_user is refused, and nobody is added. An Admin sets them on Edit User.
• If the address or number already has an account, with another firm or none, the person is linked to it; otherwise a new account is made. Either way, nobody is emailed or texted. They hear from you when you add them to a case with the invitation; see Add and remove case members with a manage key.

Reading someone

GET /users/relations/<user_id> answers everything in the list, plus their date of birth, gender, address, company and title, custom fields, notification choices and when they last signed in. GET /users/relations/<user_id>/cases lists the cases they're on, closed ones included, with each case's case_id, title, case_ref_id (your hub's ID, :: and the Tag ID) and case_status, and their case_role_id and case_designation on it.

Disabling or re-enabling someone

PUT /users/relations/<user_id> takes one field, host_user_status: 0 to disable them, 1 to re-enable them. It answers 204.

curl -X PUT https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/users/relations/cu-4f1c2a9e8b7d60 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host_user_status": 0}'

• A disabled person is refused everywhere in your hub from their next click, but stays on their cases and keeps their account for other firms. See Disable or re-enable a user.
• When their status changes, they're emailed, or texted if they have no email, that their access was disabled or restored. Sending the status they already have changes nothing and sends nothing.
• A key can disable or re-enable Managers and Users, but not Admins or itself.

If a call is refused

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