Overview
The CareAgt API is a JSON REST API over HTTPS. It is the same API the CareAgt portal uses, so anything a person can see in the portal, a key with the right scope can read through the API.
https://portal.careagt.com/api/v1
The partner API and webhooks are included in the Enterprise plan. Ask us for access.
Authentication
Every request carries an API key. Keys look like cak_… and are shown only once when issued. Send the key in either header:
Authorization: Bearer cak_your_key_here
X-API-Key: cak_your_key_here
Each key has scopes that decide what it may do, named <area>:read or <area>:write, for example cases:read, sms:write or contacts:read. A key can also be limited to a list of IP addresses and has a rate limit per minute.
Which account
A key is linked to one or more CareAgt accounts. If it is linked to more than one, name the account with the account_id query parameter.
Acting for a user
To record an action as done by a particular person, such as assigning a case, send X-On-Behalf-Of with that user’s id. The user must be active in the account the request acts on.
curl https://portal.careagt.com/api/v1/whoami \
-H "Authorization: Bearer $CAREAGT_KEY"
Requests and errors
- JSON in, JSON out. Send
Content-Type: application/jsonon writes. Times are ISO 8601 in UTC. - Safe retries. Send an
Idempotency-Keyheader with any write. Repeating the request with the same key returns the original result instead of doing the work twice. - Request ids. Every response carries
X-Request-Id. Include it when you contact support. - Rate limits. Over the limit you get
429with aRetry-Afterheader in seconds. - Errors are a non-2xx status with a body like the one below.
{ "error": "invalid_api_key", "detail": "the key has been revoked" }
| Status | Meaning |
|---|---|
| 400 | The request is malformed or a field is missing. |
| 401 | invalid_api_key: the key is unknown, revoked or expired. |
| 403 | The key lacks the scope, or ip_not_allowed: the request came from an address the key does not allow. |
| 404 | Not found in the accounts this key can reach. |
| 429 | rate_limited: wait for Retry-After seconds. |
Endpoints
The most used endpoints, grouped by area. Paths are relative to the base URL.
Account
| GET /whoami | Who the key acts as: the account, the plan’s features and whether it may write. A quick way to test a key. |
Calls
| GET /calls | Calls, newest first, with caller, agent, duration and outcome. |
| GET /calls/{id} | One call with its summary, transcript and the details the agent collected. |
| GET /calls/{id}/timeline | What happened during the call, step by step. |
| GET /calls/{id}/recording | The recording, when recording is on. |
Cases
A case is the follow-up a call or text creates: who it is for, what should happen next and whether it is done.
| GET /cases | Cases, filtered by status, assignee, type or date. |
| POST /cases | Open a case. |
| GET /cases/{id} | One case with its calls, texts and notes. |
| PATCH /cases/{id} | Change priority, due date or status. |
| GET /cases/by-external-id/{externalId} | Find a case by the id your system gave it. |
| POST /cases/{id}/assign | Assign to a user or group. |
| POST /cases/{id}/notes | Add a note. |
| PATCH /cases/{id}/outcome | Record the outcome and close the case. |
| GET /cases/{id}/events | The case’s full timeline. |
Contacts
| GET /contacts | Contacts, searchable by name or number. |
| GET /contacts/lookup | Find the contact for a phone number. |
| POST /contacts | Create a contact. |
| PATCH /contacts/{id} | Update a contact. |
| DELETE /contacts/{id} | Delete a contact. |
Text messages
| GET /sms/threads | Text conversations. |
| GET /sms/threads/{id}/messages | Messages in a conversation. |
| POST /sms/threads/{id}/messages | Reply in a conversation: {"body": "…"}. |
| POST /sms/send | Start a conversation: {"line_id": 12, "to": "+15555550123", "body": "…"}. |
Webhooks
| GET /webhooks | Your subscriptions. |
| POST /webhooks | Subscribe a URL to events. |
| PATCH /webhooks/{id} | Change URL, events, mode or secret. Add ?rotate_secret=true for a new secret. |
| DELETE /webhooks/{id} | Remove a subscription. |
| POST /webhooks/{id}/test | Send a signed sample to your receiver. |
| GET /webhooks/deliveries | Recent deliveries and their results. |
Sign-in links
| POST /sso/link | A one-time link that signs a user into the portal. See below. |
Webhooks
Webhooks tell your system when something happens, so you don’t have to poll. Subscribe a URL to the events you want:
curl https://portal.careagt.com/api/v1/webhooks \
-H "Authorization: Bearer $CAREAGT_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/careagt", "events": ["call.completed", "case.opened"], "payload_mode": "full"}'
The response includes the signing secret. It is shown only once, so store it.
Events
| call.completed | A call ended. Carries the transcript, the summary and the details the agent collected. |
| sms.received | A text came in. |
| sms.queued | A text was accepted for sending. |
| case.opened | A new case was opened. |
| assigned · claimed · released | A case was assigned, taken or handed back. |
| snoozed | A case was put aside until later. |
| lifecycle.changed | A case moved to a new status. |
| outcome.set · priority.set · due.set | A case’s outcome, priority or due date changed. |
| note.added · activity.added | A note or activity was added to a case. |
| account.created · user.updated · agent.config_changed | Account, user or agent settings changed. |
Delivery
Each delivery is a POST with a JSON body:
{
"event_id": "01J…",
"event_type": "call.completed",
"account_id": 42,
"case_id": 1187,
"occurred_at": "2026-11-09T15:04:05Z",
"payload_mode": "full",
"data": { … }
}
Headers: CareAgt-Signature, CareAgt-Event, CareAgt-Event-Id and CareAgt-Delivery. Answer with any 2xx status. Failed deliveries are retried with growing delays for about 24 hours. The same event can arrive more than once, so use event_id to skip duplicates.
Identifiers only
Set "payload_mode": "ids_only" and the body carries identifiers, statuses and times, but no names, phone numbers, transcripts or note text. Your system then fetches the details over the API under its key’s scopes. Use this when callers’ information, such as health information, should not travel in a webhook.
Verifying signatures
Every delivery is signed so you can confirm it came from CareAgt. The header looks like this:
CareAgt-Signature: t=1762700645,v1=5f8d…c41a
The signature is HMAC-SHA256, keyed with your subscription’s secret, over the timestamp, a period and the raw request body. Reject deliveries whose timestamp is more than 5 minutes from your clock, so a captured delivery cannot be replayed.
// Node.js
import crypto from "node:crypto";
export function verify(secret, header, rawBody) {
const parts = Object.fromEntries(header.split(",").map(p => p.trim().split("=")));
const t = Number(parts.t);
if (!t || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto.createHmac("sha256", secret)
.update(`${t}.${rawBody}`).digest("hex");
return expected.length === parts.v1.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
# Python
import hmac, hashlib, time
def verify(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.strip().split("=", 1) for p in header.split(","))
t, sig = int(parts.get("t", 0)), parts.get("v1", "")
if not t or not sig or abs(time.time() - t) > 300:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig)
Verify against the raw body exactly as received, before parsing it as JSON.
Sign-in links
Put the CareAgt portal inside your own application without a second password. Your server asks for a one-time link for a user, and the user’s browser opens it:
curl https://portal.careagt.com/api/v1/sso/link \
-H "Authorization: Bearer $CAREAGT_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": 311, "embed": true}'
The link works once and expires within minutes. With "embed": true the portal opens without its own header and navigation, ready to sit inside your page. Requesting links needs a key with account:write. To frame the portal on your own website, tell us your site’s address so we can allow it.
Getting access
API keys are issued by CareAgt for Enterprise accounts and approved partners. Write to support@careagt.com with your account name, what you’re building, the scopes you need and, if you want one, the IP addresses to allow. You can also book a call to talk it through.