Connect your own system to Ventcare

Quick start

1. 1. Sign in and open Integrations in your provider dashboard. Not listed yet? Create your listing first.
2. 2. Create a named key and copy it — it is shown once.
3. 3. Call the bookings endpoint below to confirm the key works.
4. 4. Add your https endpoint, press Send test, and verify the signature.
5. 5. Go live — write visit statuses back to Ventcare so clients see the same history you do.

curl "https://ventcare.org/api/public/v1/bookings?limit=5" \
  -H "Authorization: Bearer vc_live_your_key"

Authentication

Every request carries your key as a bearer token over https. We store only a one-way hash of the key, so nobody at Ventcare can read it back to you. A key reaches exactly one listing — yours — and can be revoked instantly. Base URL: https://ventcare.org. All responses are JSON and never cached.

Authorization: Bearer vc_live_9f3c…      # required on every call
Accept: application/json
Content-Type: application/json          # on POST only

Keep keys on your server. Never put one in a browser, mobile app or shared spreadsheet. If a key leaks, revoke it in Integrations and create a new one — existing bookings are unaffected.

Permissions

Each key carries a set of permissions. Requesting an endpoint without its permission returns 403 — nothing is partially applied.

Endpoints

Successful replies are wrapped in { data: … }. Ventcare's own fee, payout and tax figures are never returned.

{
  "data": {
    "id": "6f1c…", "name": "Nuru Counselling", "type": "therapist",
    "headline": "Trauma-informed therapy in Nairobi",
    "city": "Nairobi", "status": "approved", "verified": true,
    "rating": 4.8, "review_count": 21, "price_per_session": 3500,
    "specialties": ["Anxiety", "Trauma"],
    "languages": ["English", "Kiswahili"],
    "session_modes": ["in_person", "online"]
  }
}

{
  "data": [
    {
      "id": "b2a9…", "name": "Individual therapy (50 min)",
      "description": "One-to-one session.", "price": 3500,
      "duration_minutes": 50, "category": "therapy", "is_active": true
    }
  ]
}

{
  "data": {
    "hours": [
      { "id": "…", "day_of_week": 1, "start_time": "09:00", "end_time": "17:00" }
    ],
    "blocks": [
      { "id": "…", "starts_at": "2026-10-02T06:00:00Z",
        "ends_at": "2026-10-02T12:00:00Z", "reason": "Away" }
    ]
  }
}

GET /api/public/v1/bookings?from=2026-09-01T00:00:00Z&status=confirmed&limit=100

{
  "data": [
    {
      "id": "d41f…", "listing_id": "6f1c…",
      "service": { "id": "b2a9…", "name": "Individual therapy (50 min)",
                   "duration_minutes": 50 },
      "scheduled_at": "2026-09-24T11:00:00Z",
      "status": "confirmed", "payment_status": "paid",
      "amount": 3500, "currency": "KES",
      "session_mode": "online", "notes": null,
      "client": { "name": "A. Wanjiru", "phone": "+2547…",
                  "email": "client@example.com" },
      "created_at": "2026-09-20T08:14:00Z"
    }
  ]
}

{ "data": { "id": "d41f…", "status": "confirmed", … } }

POST /api/public/v1/bookings/d41f…/status
Content-Type: application/json

{ "status": "completed" }

{ "data": { "id": "d41f…", "status": "completed", … } }

Webhooks

Register one https endpoint in your dashboard and we POST a small JSON body whenever a booking changes. Reply with any 2xx status within ten seconds; anything else is retried up to five times with growing gaps, and every attempt is listed in your dashboard.

Headers and body

POST https://your-system.example/ventcare
x-ventcare-event: booking.paid
x-ventcare-timestamp: 1737400000
x-ventcare-signature: hex(hmac_sha256(secret, timestamp + "." + rawBody))

{
  "event": "booking.paid",
  "created_at": "2026-09-21T11:02:31.204Z",
  "data": {
    "booking": {
      "id": "d41f…", "scheduled_at": "2026-09-24T11:00:00Z",
      "status": "confirmed", "payment_status": "paid",
      "amount": 3500, "currency": "KES",
      "client": { "name": "A. Wanjiru", "phone": "+2547…",
                  "email": "client@example.com" }
    }
  }
}

Verifying a call

Recompute the signature over the raw body before parsing it, compare in constant time, and reject anything with a timestamp older than five minutes.

// Node.js
import { createHmac, timingSafeEqual } from "crypto";

function verify(rawBody, headers, secret) {
  const ts = headers["x-ventcare-timestamp"];
  const sent = headers["x-ventcare-signature"];
  if (!ts || !sent) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(sent, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

# PHP
$ts   = $_SERVER['HTTP_X_VENTCARE_TIMESTAMP'] ?? '';
$sent = $_SERVER['HTTP_X_VENTCARE_SIGNATURE'] ?? '';
$raw  = file_get_contents('php://input');

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }
$expected = hash_hmac('sha256', $ts . '.' . $raw, $secret);
if (!hash_equals($expected, $sent)) { http_response_code(401); exit; }

http_response_code(200);

The same booking event can arrive more than once after a retry. Treat the booking id plus event as the key and make your handler idempotent. Rotating your signing secret in Integrations invalidates the old one immediately.

Errors & limits

Up to 120 calls a minute per key. Errors always look the same:

{ "error": { "code": "forbidden",
             "message": "This key does not have the \"bookings:write\" permission." } }

Retry 429 and 503 with exponential backoff. Never retry 401 or 403 — fix the key first. For diary sync, poll the bookings endpoint no more than once a minute and prefer webhooks for anything time-sensitive.

Versioning & support

The version lives in the path (/api/public/v1/). We only add fields and endpoints within a version; anything that would break existing integrations goes into a new one, and we write to every provider with an active key before that happens. A machine-readable description is available at /api/public/v1/openapi.json.

Questions, or need an endpoint that isn't here? Email sales@ventcare.org or use the contact form and tell us what your system needs.