Medtimes Developers R1.2

Ask Medtimes to deliver care.

The Care Request API is the preferred integration surface for applications that need healthcare delivered. Your app submits one non-emergency care request; Medtimes routes it internally to Hospital Admin or the Matron, coordinates delivery, and reports a partner-safe lifecycle back to you.

Base URL

https://developers.medtimes.health/api/v1/partner

Use Authorization: Bearer mt_test_… in sandbox. Send fictional data only with test keys.

Operational model

3rd party app → Medtimes API → Hospital Admin or Matron.

The API never exposes workforce rosters, internal notes, Matron assignments or hospital-operational details to partners.

1. Register or link a patient

curl 'https://developers.medtimes.health/api/v1/partner/patients' \
  -H 'Authorization: Bearer YOUR_TEST_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: patient-example-001' \
  -d '{
    "external_id":"your-patient-001",
    "first_name":"Fictional", "last_name":"Person",
    "date_of_birth":"1990-01-01", "gender":"other",
    "phone":"+27000000000",
    "consent":{
      "care":true, "share_summary":true,
      "version":"2026-09-r1",
      "evidence":"your-consent-record-reference"
    }
  }'

Save data.id. Care requests require current consent to care. The partner retains its source consent evidence; Medtimes stores the receipt/reference.

2. Submit a Care Request

curl 'https://developers.medtimes.health/api/v1/partner/care-requests' \
  -H 'Authorization: Bearer YOUR_TEST_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: care-example-001' \
  -d '{
    "patient_id":"PATIENT_UUID",
    "external_id":"your-case-001",
    "request_type":"consultation",
    "service":"general medical consultation",
    "delivery_preference":"remote",
    "modality":"telephone",
    "priority":"routine",
    "reason":"Fictional persistent abdominal discomfort",
    "emergency":false,
    "contact_confirmed":true
  }'

Request types: consultation, diagnostics, nursing, procedure, referral, home_visit, specimen_collection, workplace_health, health_desk, physical_assessment, mobile_clinic, other.

Delivery preferences: remote, clinic, home, workplace, mobile, facility, unspecified. Off-site physical delivery requires a location object. Priorities are routine or urgent. This endpoint rejects emergency requests.

3. Medtimes routes it internally

Hospital Admin

Consultations, referrals, procedures, facility care and hospital coordination normally enter the Hospital Admin queue. Hospital Admin can create a linked clinical encounter, after which the existing clinician workflow remains authoritative.

Matron

Nursing, home visits, specimen collection, workplace health, Health Desks, physical assessments and mobile-clinic work normally enter the Matron queue. The Matron owns physical-care workforce coordination.

Medtimes may reroute requests between those queues. That routing is intentionally internal; your application works against the stable Care Request lifecycle.

4. Follow the Care Request

curl 'https://developers.medtimes.health/api/v1/partner/care-requests/CARE_REQUEST_UUID' \
  -H 'Authorization: Bearer YOUR_TEST_KEY'

Partner-visible states are received, accepted, scheduled, in_progress, requires_information, completed, cancelled and declined. When more information is required, partner_message may contain the operational question. Internal staffing and notes are never returned.

Cancel before work starts with POST /care-requests/{id}/cancel using care_requests:write.

5. Linked clinical encounters

Hospital Admin can turn a care request into a clinical encounter. The clinical encounter remains subject to current consent, clinician credential verification and all live-care gates. Assignment, start and completion of that linked encounter automatically synchronise safe lifecycle state back to the Care Request.

Low-level /consultations endpoints remain available for compatible integrations, but new care-delivery integrations should prefer /care-requests.

Webhooks

R1.2 adds these care events: care_request.received, care_request.accepted, care_request.scheduled, care_request.in_progress, care_request.requires_information, care_request.completed, care_request.cancelled, care_request.declined.

{
  "url":"https://your-callback.example/medtimes/events",
  "events":["care_request.scheduled","care_request.completed"]
}

Care-request webhook payloads contain only the event ID, environment, care-request ID, your external ID and partner-safe status. Verify Medtimes-Signature, deduplicate event IDs and fetch current state for authority.

API contract

Method / path	Scope
`GET /patients, /patients/{id}`	`patients:read`
`POST /patients, /patients/{id}/consent/withdraw`	`patients:write`
`GET /care-requests, /care-requests/{id}`	`care_requests:read`
`POST /care-requests, /care-requests/{id}/cancel`	`care_requests:write`
`GET /consultations, /consultations/{id}`	`consultations:read`
`POST /consultations, /consultations/{id}/cancel`	`consultations:write`
`GET /documents/{id}`	`documents:read`
`GET /webhooks, /webhook-deliveries`	`webhooks:read`
`POST /webhooks; DELETE /webhooks/{id}`	`webhooks:write`

Writes require an Idempotency-Key. Lists use page and per_page (1–100). Responses include X-Request-ID. Test keys can never access live records.

Before live care

R1.2 does not enable live healthcare. Live access still requires the developer-app review, partner activation, global clinical readiness, verified clinicians, Hospital Admin and Matron operational coverage, secure credentials, restore verification and CLINICAL_LIVE_ENABLED=true.