An API you can integrate before lunch.

1 · Get a key

An admin creates API keys in the app under Admin → Integrations. Keys look like mza_<prefix>_<secret>, are shown once, and are scoped — a lead-pushing key cannot read charts. Revoke any time; revocation is immediate.

# Every call: the key is a bearer token, same as a login token.
curl https://medappz.com/v1/leads \
  -H "Authorization: Bearer mza_ab12cd34ef_...yoursecret..."

2 · Push a lead from your website or CRM

The most-built integration: an enquiry form on your site lands in the clinic's LeadDesk pipeline, deduplicated by phone, worked to a consultation.

curl -X POST https://medappz.com/v1/leads \
  -H "Authorization: Bearer mza_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Asha Verma",
    "phone": "+919876543210",
    "source": "website",
    "note": "Asked about a skin consultation"
  }'

# 201 → {"data": {"id": "…", "status": "new", …}}

The Idempotency-Key header is the rule worth learning once: send it on every write, and a retried request (timeouts, double-clicks, queue replays) can never create two leads, two bills, or two bookings.

3 · Hear back with webhooks

Subscribe to events (lead created, appointment booked, bill paid) and MedAppz calls your URL — signed, retried with backoff, and every delivery inspectable in the app.

# Every delivery carries a signature header:
#   x-medappz-signature: t=1722578400,v1=<hex hmac>
# Verify: HMAC-SHA256 over "<t>.<raw body>" with your webhook secret.

const [tPart, vPart] = header.split(',');
const ts = tPart.slice(2), theirs = vPart.slice(3);
const mine = crypto.createHmac('sha256', SECRET)
  .update(ts + '.' + rawBody).digest('hex');
// timing-safe compare mine vs theirs; reject if ts is older than 5 min.

Use the Send test event button in Admin → Integrations to get a signed hello-world delivery before wiring anything real.

The three rules of the house

They keep every integration safe, and the API enforces them rather than trusting you to remember.

• Tenancy comes from the token, never the payload. There is no organisation id parameter anywhere — a key can only ever touch its own clinic's data.
• Writes are idempotent. Send an Idempotency-Key; retries become no-ops, not duplicates.
• Patient messaging is consent-gated. Anything that would message a patient checks their consent record first and refuses without it — your integration cannot spam even by accident.

Errors you can act on

Every error is a structured envelope: a stable code, a human message, and the request id to quote when you write to us.

{
  "error": {
    "code": "BUSINESS_RULE_VIOLATION",
    "message": "This patient already has a session on this date.",
    "requestId": "req_01J…"
  }
}

The full reference

The complete OpenAPI definition — every endpoint, schema and permission — ships in the repository as docs/openapi.json and renders at /v1/docs on non-production environments. Rate limits are per key and generous for clinic-scale traffic; public endpoints are tighter.

Building something bigger — an ABDM bridge, a device feed, a lab analyzer? Write to hello@medappz.com and an engineer answers, not a queue. Or start where every integration starts: create a practice and issue yourself a key.