CareVieo Developer API

Getting started

In Agency Settings, open Developer / API. Owners and admins can activate the API add-on, complete the BAA, and create a key with the minimum scopes required. Save the full key when it is shown once.

https://carevieo.com/api/public/public-api/v1

Run your first call with a key supplied from a secure environment variable:

curl "https://carevieo.com/api/public/public-api/v1/me" -H "Authorization: Bearer $CAREVIEO_API_KEY"

$headers = @{ Authorization = "Bearer $env:CAREVIEO_API_KEY" }
Invoke-RestMethod -Uri "https://carevieo.com/api/public/public-api/v1/me" -Headers $headers

const response = await fetch("https://carevieo.com/api/public/public-api/v1/me", {
  headers: { Authorization: `Bearer ${process.env.CAREVIEO_API_KEY}` }
});
console.log(response.status, await response.json());

import os, requests
r = requests.get("https://carevieo.com/api/public/public-api/v1/me",
    headers={"Authorization": "Bearer " + os.environ["CAREVIEO_API_KEY"]})
print(r.status_code, r.json())

Authentication & scopes

Send Authorization: Bearer <key>. The key determines the agency and environment; never send agency_id. Revoked, expired, and suspended keys cannot access data.

Live shift writes remain unavailable until shared scheduling validation is complete. Sandbox writes are available.

Pagination & filtering

Lists accept limit (1–100; default 50), cursor and updated_since (ISO 8601). Follow next_cursor until it is null. Shifts also accept from, to, caregiver_id, client_id and status; source distinguishes open shifts and assignments. All timestamps are ISO 8601 and IDs are stable UUIDs.

Errors

{
  "error": {
    "code": "forbidden_scope",
    "message": "Required scope: visits.read",
    "request_id": "request-uuid"
  }
}

401 unauthorized; 403 forbidden_scope, plan_required or baa_required; 404 not_found; 409 idempotency_conflict / idempotency_in_progress; 422 validation_error with field-level errors; 429 rate_limited (Retry-After); 500 internal_error / audit_unavailable.

Rate limits & quotas

Monthly quotas do not block calls. Overage costs $2 per 1,000 calls. Successful Pulse matching costs $0.05, referral triage $0.10 and document extraction $0.25. Monthly Starter/Pro onboarding is $500; annual prepay and Enterprise waive onboarding. Response headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining and X-Quota-Remaining.

Idempotency

POST and PATCH require Idempotency-Key. Reuse the same key and identical request to replay the stored response for 24 hours. Concurrent duplicates return 409 idempotency_in_progress; changed bodies return 409 idempotency_conflict. One-time webhook secret creation/rotation must omit this header so secrets are never replay-stored. Operational DELETE is not supported; use status changes.

Sandbox

Pro and Enterprise support cv_test_ keys. Synthetic Test Client and Test Caregiver records are isolated from operational records; sandbox reads and writes never access live records. Pulse responses are canned and free, with no billable overage. Reset sandbox data in Developer settings. The same base URL works in both environments.

Webhooks · delivery coming soon

Configure events in the Webhooks tab. Delivery remains disabled pending secure outbound delivery infrastructure. Fetch details through the authenticated API; thin event payloads contain identifiers and scheduling metadata, never names, diagnoses or notes.

{
  "id": "event-uuid",
  "type": "visit.completed",
  "created_at": "2026-10-28T21:11:00Z",
  "agency_id": "agency-uuid",
  "api_version": "v1",
  "data": {
    "object": "visit",
    "id": "visit-uuid",
    "status": "completed"
  }
}

Event catalog

• invoice.created — Invoice created
• invoice.paid — Invoice paid
• invoice.sent — Invoice sent
• payment.failed — Payment failed
• client.admitted — Client became active
• client.created — Client created
• client.updated — Client updated
• contact.created.v1 — Thin v1 contact created; legacy contact.created unchanged
• contact.updated.v1 — Thin v1 contact updated; legacy contact.updated unchanged
• caregiver.credential_hold_changed — Caregiver credential hold changed
• credential.expired — Credential expired
• credential.expiring — Credential expires in 30, 14 or 7 days
• incident.reported — Geofence alert or escalation flag reported
• referral.received — New operational or AI referral received
• referral.updated — Referral updated
• shift.cancelled — Shift cancelled
• shift.created — Shift created
• shift.filled — Open shift filled
• shift.unfilled — Open shift approaching start unfilled
• shift.updated — Shift updated
• visit.completed — Visit completed
• visit.evv_exception — EVV verification exception
• visit.missed — No clock-in after scheduled start and grace
• visit.started — Visit clock-in recorded

Verify CareVieo-Signature: t=<unix>,v1=<HMAC-SHA256(t + '.' + raw_body)>. Reject timestamps outside five minutes, compare timing-safely, and deduplicate CareVieo-Event-Id. CareVieo-Event-Type names the event.

Node verification

import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, header, secret) {
  const parts = header.split(",");
  const t = parts.find(p => p.startsWith("t="))?.slice(2);
  if (!t || !/^\d+$/.test(t) || Math.abs(Date.now()/1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(t + ".").update(rawBody).digest();
  return parts.filter(p => p.startsWith("v1=")).some(p => {
    const hex = p.slice(3); if (!/^[a-f0-9]{64}$/.test(hex)) return false;
    return timingSafeEqual(expected, Buffer.from(hex, "hex"));
  });
}

Python verification

import time, hmac, hashlib
def verify(raw_body, header, secret):
    parts = header.split(",")
    t = next((p[2:] for p in parts if p.startswith("t=")), None)
    if not t or not t.isdigit() or abs(time.time()-int(t)) > 300: return False
    expected = hmac.new(secret.encode(), t.encode()+b"."+raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, p[3:]) for p in parts if p.startswith("v1="))

Any 2xx succeeds. Retry backoff: 1m, 5m, 30m, 2h, 6h, 12h and 24h, up to three days; then disable and notify owners/admins. Retries retain the event ID. Event replay retention is 30 days. Deliveries do not consume API quota.

HIPAA & BAA

A signed agency BAA is required before creating or using keys. Every authenticated call is agency-scoped and audit-logged. Encrypted fields, tokens, secrets, signature images and verification PIN hashes are never returned. PHI-heavy client reads/writes require dedicated scopes. Store keys only in secure server environments, request minimum scopes, and avoid logging response bodies containing PHI.

Changelog

v1 launch preview · October 28, 2026 — scoped reads, validated client/contact/referral writes, synthetic sandbox, enterprise exports and metered Pulse. Webhook delivery and live scheduling activation remain pending. Not yet published.