For: Admins
Understand what the API can do
Learn what a manage key and a hub key can each reach, why every key acts as the Virtual Assistant, and where the full technical listing is.
In this article2 sections
The API lets your own software, such as a case management system, work with your hub without anyone using the screens. It's called with an API keyKey A secret token, created under Integration, that lets your own software use the hub's API., and there are two kinds: a manage key for the Admin Panel's work, such as cases and people, and a hub key for the work inside cases.
How it works
Two keys, two APIs. Each kind of key calls its own address, followed by your hub's ID, and is refused by the other.
| Key | Address | What it reaches |
|---|---|---|
| Manage key | https://prd-api-manage.caseactive.com/v1/<hub id>/ | Cases and who's on them, people and their access, roles, stages, search, and invoices to read. Imports are at https://prd-api-manage.caseactive.com/v1/integration/<hub id>/. |
| Hub key | https://prd-api-app.caseactive.com/v1/<hub id>/ | Everything inside every case: posts and comments, files, forms, e-signs, tasks, invoices, events, notes and the case's details |
What a manage key can call. Only these. Any other call in the Admin Panel's API answers 403 BotNotAllowedException.
- Cases: list, create, read, update and delete. See Create and update cases with a manage key.
- Case members: list, add and remove. See Add and remove case members with a manage key.
- People: list, add, read, and disable or re-enable. See Add and update users with a manage key.
- Roles and stages: read. See Read roles with a manage key.
- Custom fields: read your case and user field pages. See Create and update cases with a manage key.
- Invoices: read. See Read invoices with a manage key.
- Search. See Search cases and users with a manage key.
- Imports. See Run an import with a manage key.
Every key is your Virtual Assistant. A key signs in as 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.. What it posts shows under the Virtual Assistant's name and badge, and what it changes is recorded as the Virtual Assistant's. The Virtual Assistant is on every case, so a hub key reaches every case in your hub. It can do what the Virtual Assistant's role allows, which by default is what staff can do, and a closed case is read-only to it. A hub key can't create cases, add or remove people, pay invoices, or open or answer inquiries.
Keys don't expire. A key works until an Admin switches it off or deletes it. Limit each one to your system's public IPv4 address; see Restrict or revoke an API key.
The technical pages. Each API publishes a full technical listing of its calls, with no sign-in needed:
| Manage key | Hub key | |
|---|---|---|
| Interactive (Swagger UI) | https://prd-api-manage.caseactive.com/ | https://prd-api-app.caseactive.com/ |
| Reference (ReDoc) | https://prd-api-manage.caseactive.com/redoc | https://prd-api-app.caseactive.com/redoc |
| OpenAPI document | https://prd-api-manage.caseactive.com/openapi.json | https://prd-api-app.caseactive.com/openapi.json |
They list every call the apps themselves make, including many a manage key can't, with nothing marking which. The list above says what a manage key can use. To try a call on the interactive page, choose Authorize and paste your key.
A locked hub. While your hub's Admin Panel is locked after a failed payment, a manage key is refused with 403 ManageBillingInactiveException. A hub key keeps working until the portal becomes read-only: 14 days after the failed payment if it's still unpaid, or the day a cancelled subscription ends. From then on a hub key can still read, but every change is refused with 403 BillingReadOnlyException, until an Admin restarts the subscription.
When to use it
Use a manage key to keep your hub in step with another system: create cases, add clients and put them on their cases, take people's access away when they leave, or load many rows at once from a file. Use a hub key to work inside cases from your own software, such as adding a post when something changes in your system.
To hear about changes in your hub as they happen, rather than asking for them, use a webhook; see Set up a webhook. To create a key, see Create an API key.