The CarelyCloud API.

Authentication

An admin creates keys in Settings → Integrations. The key is shown once. Send it on every request in the X-API-Key header.

curl https://carelycloud-production.up.railway.app/clinics/me \
  -H "X-API-Key: cc_live_xxxxxxxxxxxxxxxxxxxx"

A key acts for the clinic, not for a person, and it can only touch part of the API:

• Read: appointments, patients (with notes and files), practitioners, availability, services, the clinic profile and dashboard stats.
• Write: appointments and patients, including their notes and files.
• Everything else (team, settings, billing, integrations, AI notes) answers 403 API_KEY_SCOPE.

Access is checked on every request against the clinic's plan. When a trial ends or a subscription is suspended, every key answers 402 immediately — nothing to revoke by hand. Revoking a key in Settings takes effect on the next request.

Conventions

• Base URL: https://carelycloud-production.up.railway.app
• JSON in and out. Send Content-Type: application/json on writes.
• Dates are ISO 8601 with timezone. We store UTC; send whatever offset you like and we convert. Slots come back in the clinic's timezone.
• Lists that paginate take page (1-based) and limit. GET /appointments without page returns the whole range.
• Errors are JSON with a stable code, a message and optional details:

{ "code": "SLOT_TAKEN", "message": "SLOT_TAKEN", "details": null }

Appointments

Filter by range (start, end), practitioner, patient, status, or free text (q). Without a range you get everything, so pass one.

curl "https://carelycloud-production.up.railway.app/appointments?start=2026-09-15T00:00:00Z&end=2026-09-15T23:59:59Z&doctor_id=3" \
  -H "X-API-Key: cc_live_..."

Creating an appointment goes through the same rules as the app. The practitioner is required, and the slot must be inside their working hours and free:

curl -X POST https://carelycloud-production.up.railway.app/appointments \
  -H "X-API-Key: cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "doctor_id": 3,
    "service_id": 1,
    "patient_id": 42,
    "start_at": "2026-09-15T15:00:00Z",
    "end_at":   "2026-09-15T15:30:00Z",
    "status":   "confirmed",
    "channel":  "manual",
    "notes":    "Booked from our CRM"
  }'

Status changes go through PATCH. Allowed transitions: scheduled → confirmed | cancelled | no_show; confirmed → completed | cancelled | no_show. Completed, cancelled and no_show are final. DELETE is a shortcut for cancelling.

curl -X PATCH https://carelycloud-production.up.railway.app/appointments/981 \
  -H "X-API-Key: cc_live_..." -H "Content-Type: application/json" \
  -d '{ "status": "cancelled", "cancel_reason": "Patient called" }'

Patients

Creating a patient checks for likely duplicates by phone or email and answers 409 with the matches; pass force=true to create anyway.

curl -X POST "https://carelycloud-production.up.railway.app/patients?force=false" \
  -H "X-API-Key: cc_live_..." -H "Content-Type: application/json" \
  -d '{
    "first_name": "Marta",
    "last_name":  "Ríos",
    "phone":      "+50499990000",
    "email":      "marta@example.com",
    "birth_date": "1992-04-12",
    "gender":     "female",
    "preferred_channel": "whatsapp"
  }'

Search matches name, phone and email. Pagination is 20 per page by default, 500 maximum.

curl "https://carelycloud-production.up.railway.app/patients?q=marta&page=1&limit=20" -H "X-API-Key: cc_live_..."

Practitioners, availability and services

Read-only. Practitioners and services are managed from the app.

curl "https://carelycloud-production.up.railway.app/doctors/3/slots?date=2026-09-15&service_id=1" -H "X-API-Key: cc_live_..."

[
  { "start_at": "2026-09-15T15:00:00-06:00", "end_at": "2026-09-15T15:30:00-06:00", "available": true },
  { "start_at": "2026-09-15T15:15:00-06:00", "end_at": "2026-09-15T15:45:00-06:00", "available": false }
]

Webhooks

An admin registers an https URL in Settings → Integrations and picks the events. We POST each one as it happens, once, with an 8-second timeout. No retries: if your endpoint is down, the delivery shows as failed in the log and you can replay from the API.

Every delivery carries the event name and an HMAC-SHA256 signature of the raw body, using the secret shown once when the endpoint was created:

POST https://your-server.example.com/carelycloud
Content-Type: application/json
X-CarelyCloud-Event: appointment.confirmed
X-CarelyCloud-Signature: sha256=3f1a...

{
  "event": "appointment.confirmed",
  "created_at": "2026-09-15T14:02:11.480Z",
  "data": {
    "id": 981, "clinic_id": 6, "doctor_id": 3, "service_id": 1, "patient_id": 42,
    "start_at": "2026-09-15T15:00:00Z", "end_at": "2026-09-15T15:30:00Z",
    "status": "confirmed", "channel": "online"
  }
}

Verify the signature before trusting a payload. Compare with a constant-time function:

# Python
import hmac, hashlib
def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

// Node
const crypto = require("crypto")
function verify(secret, rawBody, header) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header))
}

• Only https URLs on public hosts. Redirects are not followed.
• Respond 2xx within 8 seconds; do the work afterwards.
• The log keeps the last 100 deliveries per endpoint, with status and duration.
• The Test button in Settings sends a sample event so you can check your endpoint before going live.

Zapier, n8n and Make

They do not need a native app: a webhook trigger plus an HTTP action covers the whole API.

• Zapier: a "Webhooks by Zapier · Catch Hook" trigger receives events; a "Webhooks by Zapier · Custom Request" action calls the API with the X-API-Key header.
• n8n: the Webhook node receives events; the HTTP Request node calls the API. Use a Header Auth credential for the key.
• Make: the Custom Webhook module receives events; the HTTP module calls the API.

Typical first automation: patient.created → add the patient to your CRM; appointment.confirmed → post to the clinic's Slack or WhatsApp group.

Errors