Documentation

API Reference

Complete endpoint documentation for every Cari service.

In this guide

AuthPatientsDoctorsOrganizationSchedulingSessionCDSMPIRCMMarketplaceWorkforceTreatmentsPaymentsFHIRFeedback

Base URL & Authentication

PASETO v4 token authentication and standard response envelope.

Base URL: https://api.cari.care

Authorization: Bearer <paseto_token>
Content-Type: application/json

All endpoints require authentication unless marked as Public. Obtain a token via POST /api/auth/login and include it in the Authorization header.

Standard Response Envelope

// Success (single resource)
{ "success": true, "data": { ... } }

// Success (paginated list)
{ "success": true, "data": [...], "meta": { "page": 1, "limit": 20, "total": 100 } }

// Error
{ "success": false, "error": { "code": "NOT_FOUND", "message": "Resource not found" } }

All paginated list endpoints accept page and limit query parameters. The response meta object includes total count for client-side pagination.

Auth Service

User registration, authentication, token management, and multi-factor authentication.

Endpoints

POST
/api/auth/registerPublic

Register a new user

POST
/api/auth/loginPublic

Authenticate and receive tokens

POST
/api/auth/refreshPublic

Refresh an expired access token

POST
/api/auth/logout

Invalidate current session

GET
/api/auth/mePublic

Get current authenticated user

POST
/api/auth/verify-emailPublic

Verify email address

POST
/api/auth/forgot-passwordPublic

Request password reset email

POST
/api/auth/reset-passwordPublic

Reset password with token

POST
/api/auth/social-loginPublic

OAuth social login

GET
/api/auth/referral/:codePublic

Look up referral code info

MFA Endpoints

POST
/api/auth/mfa/enroll

Enroll in TOTP-based MFA

POST
/api/auth/mfa/verify

Verify MFA enrollment with TOTP code

POST
/api/auth/mfa/challenge

Submit MFA challenge during login

POST
/api/auth/mfa/disable

Disable MFA for current user

Admin Endpoints

GET
/api/admin/users

List all users (Super Admin)

PATCH
/api/admin/users/:id/status

Update user status (Super Admin)

GET
/api/admin/health

System health check (Super Admin)

Example: Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "doctor@hospital.org",
  "password": "SecureP@ss123"
}

// 200 OK
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "doctor@hospital.org",
      "first_name": "Sarah",
      "last_name": "Chen",
      "registration_role": "DOCTOR"
    },
    "token": "v4.public.eyJ..."
  }
}

Patients Service

Patient profiles, clinical data, lab results, immunizations, prescriptions, consent management, and GDPR compliance.

Patient Profiles

POST
/api/patients

Create a patient profile

GET
/api/patients/me

Get current patient's profile

GET
/api/patients/:id

Get a patient by ID

POST
/api/patients/:id

Update a patient profile

GET
/api/organizations/:org_id/patients

List patients in an organization

POST
/api/organizations/:org_id/patients

Register a patient for an organization

GET
/api/organizations/:org_id/patients/:patient_id

Get patient detail within org context

GET
/api/organizations/:org_id/patients/search

Search patients by MRN

Clinical Data

GET
/api/patients/:id/clinical-records

List clinical records

POST
/api/clinical-records

Create a clinical record

GET
/api/clinical-records/:id

Get a clinical record

PUT
/api/clinical-records/:id

Update a clinical record

DELETE
/api/clinical-records/:id

Delete a clinical record

GET
/api/clinical-records/:id/audit

Get audit trail for a record

Vitals

GET
/api/vitals

List vitals

POST
/api/vitals

Record a vital sign

GET
/api/vitals/:id

Get a vital record

PATCH
/api/vitals/:id

Update a vital record

DELETE
/api/vitals/:id

Delete a vital record

Lab Results & HL7v2

GET
/api/patients/:id/lab-results

List lab results for a patient

PATCH
/api/lab-results/:id/review

Review/approve a lab result

POST
/api/lab/hl7-ingest

Ingest an HL7v2 lab message

GET
/api/labs

List lab orders

POST
/api/labs

Create a lab order

GET
/api/labs/:id

Get a lab order

PATCH
/api/labs/:id

Update a lab order

POST
/api/labs/:id/cancel

Cancel a lab order

Prescriptions & E-Prescribing

GET
/api/prescriptions

List prescriptions

POST
/api/prescriptions

Create a prescription

GET
/api/prescriptions/:id

Get a prescription

POST
/api/prescriptions/:id/sign

Sign a prescription

POST
/api/prescriptions/:id/cancel

Cancel a prescription

POST
/api/eprescriptions

Create an e-prescription

GET
/api/patients/:id/eprescriptions

List patient e-prescriptions

PATCH
/api/eprescriptions/:id/transmit

Transmit to pharmacy

PATCH
/api/eprescriptions/:id/dispense

Mark as dispensed

POST
/api/eprescriptions/:id/refill

Request refill

Immunizations

GET
/api/patients/:id/immunizations

Get immunization schedule

POST
/api/patients/:id/immunizations/generate

Generate age-appropriate schedule

POST
/api/patients/:id/immunizations/administer

Record a vaccine dose

GET
/api/patients/:id/immunizations/missed

List missed vaccinations

POST
/api/patients/:id/immunizations/aefi

Report adverse event following immunization

Observations

GET
/api/observations

List observations (FHIR Observation-like)

POST
/api/observations

Create an observation

GET
/api/observations/:id

Get an observation

PATCH
/api/observations/:id

Update an observation

DELETE
/api/observations/:id

Delete an observation

Imaging

GET
/api/imaging

List imaging orders

POST
/api/imaging

Create an imaging order

GET
/api/imaging/:id

Get an imaging order

POST
/api/imaging/:id/cancel

Cancel an imaging order

Allergies

GET
/api/patients/:id/allergies

List patient allergies

POST
/api/patients/:id/allergies

Record an allergy

Patient Journey

GET
/api/patients/:id/journey

Get patient care journey timeline

POST
/api/patients/:id/journey

Record a journey event

Consent Management

GET
/api/consent

List my consents

POST
/api/consent/grant

Grant consent

POST
/api/consent/request

Request consent from a patient

GET
/api/consent/:id

Get a consent record

POST
/api/consent/:id/approve

Approve a consent request

POST
/api/consent/:id/revoke

Revoke consent

GDPR Data Subject Requests

POST
/api/patients/:id/erasure-request

Request data erasure (Art. 17)

GET
/api/patients/:id/dsr

List data subject requests

GET
/api/patients/:id/export

Export patient data (Art. 20 portability)

Example: Create a Patient

POST /api/patients
Authorization: Bearer v4.public.eyJ...
Content-Type: application/json

{
  "first_name": "Amara",
  "last_name": "Okafor",
  "date_of_birth": "1990-03-15",
  "gender": "female",
  "phone": "+234801234567",
  "email": "amara@example.com"
}

// 201 Created
{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "first_name": "Amara",
    "last_name": "Okafor",
    ...
  }
}

Doctors Service

Doctor profiles, verification workflow, clinical records management, and scheduling.

Doctor Profiles

GET
/api/doctors/searchPublic

Search doctors

GET
/api/doctors/:idPublic

Get doctor profile

GET
/api/doctors/me

Get my doctor profile

POST
/api/doctors

Create a doctor profile

PUT
/api/doctors/:id

Update a doctor profile

GET
/api/doctors/:id/availabilityPublic

Get availability summary

Verification (Admin)

GET
/api/doctors/pending

List pending doctor verifications

PATCH
/api/doctors/:id/verify

Approve or reject a doctor

Organization Membership

POST
/api/doctors/:id/organizations

Join an organization

DELETE
/api/doctors/:id/organizations/:org_id

Leave an organization

GET
/api/organizations/:org_id/doctors

List doctors in org

Clinical Records (Doctor Context)

GET
/api/clinical-records

List my clinical records

POST
/api/clinical-records

Create a clinical record

GET
/api/patients/:patient_id/clinical-records

List records for a patient

Service Requests & Diagnostic Reports

GET
/api/service-requests

List service requests (lab/imaging orders)

POST
/api/service-requests

Create a service request

PUT
/api/service-requests/:id/status

Update status

GET
/api/diagnostic-reports

List diagnostic reports

POST
/api/diagnostic-reports

Create a diagnostic report

POST
/api/diagnostic-reports/:id/sign

Sign/finalize a report

Imaging Studies

GET
/api/imaging-studies

List imaging studies

POST
/api/imaging-studies

Create an imaging study

PUT
/api/imaging-studies/:id/status

Update study status

Organization Service

Healthcare facility management, team members, rooms, admissions, finance, and messaging.

Organization CRUD

GET
/api/organizations

List organizations

POST
/api/organizations

Create an organization

GET
/api/organizations/me

Get my organizations

GET
/api/organizations/:id

Get organization details

PUT
/api/organizations/:id

Update an organization

PATCH
/api/organizations/:id/status

Update org status

Members & Invitations

GET
/api/organizations/:org_id/members

List members

PATCH
/api/organizations/:org_id/members/:user_id/role

Update member role

DELETE
/api/organizations/:org_id/members/:user_id

Remove member

GET
/api/organizations/:org_id/invitations

List invitations

POST
/api/organizations/:org_id/invitations

Send invitation

DELETE
/api/organizations/:org_id/invitations/:id

Revoke invitation

POST
/api/organizations/invitations/accept

Accept an invitation

Rooms & Admissions

GET
/api/organizations/:org_id/rooms

List rooms

POST
/api/organizations/:org_id/rooms

Create a room

GET
/api/organizations/:org_id/admissions

List admissions

POST
/api/organizations/:org_id/admissions

Admit a patient

POST
/api/organizations/:org_id/admissions/:id/discharge

Discharge

POST
/api/organizations/:org_id/admissions/:id/transfer

Transfer

Finance

GET
/api/organizations/:org_id/invoices

List invoices

POST
/api/organizations/:org_id/invoices

Create invoice

GET
/api/organizations/:org_id/payments

List payments

POST
/api/organizations/:org_id/payments

Record payment

GET
/api/organizations/:org_id/claims

List insurance claims

POST
/api/organizations/:org_id/claims

Submit claim

Messaging

GET
/api/organizations/:org_id/conversations

List conversations

POST
/api/organizations/:org_id/conversations

Create conversation

GET
/api/organizations/:org_id/conversations/:id/messages

List messages

POST
/api/organizations/:org_id/conversations/:id/messages

Send message

Staff & Leave

POST
/api/attendance/clock-in

Clock in

POST
/api/attendance/clock-out

Clock out

GET
/api/attendance/today

Today's attendance

POST
/api/leave-requests

Create leave request

POST
/api/organizations/:org_id/leave-requests/:id/approve

Approve leave

Developer API Keys

GET
/api/developer/keys

List API keys

POST
/api/developer/keys

Create API key

DELETE
/api/developer/keys/:id

Revoke API key

POST
/api/developer/keys/:id/rotate

Rotate API key

Scheduling Service

Resource management, schedule configuration, appointment booking, and telemedicine.

Resources

GET
/api/resources

List schedulable resources (doctors, rooms, equipment)

POST
/api/resources

Create a resource

GET
/api/resources/:id

Get a resource

PUT
/api/resources/:id

Update a resource

DELETE
/api/resources/:id

Delete a resource

Schedules

GET
/api/resources/:resource_id/schedules

List schedules for a resource

POST
/api/schedules

Create a schedule

GET
/api/schedules/:id

Get a schedule

PUT
/api/schedules/:id

Update a schedule

DELETE
/api/schedules/:id

Delete a schedule

Appointments

GET
/api/appointments

List appointments

POST
/api/appointmentsPublic

Book an appointment

GET
/api/appointments/availability

Check availability

GET
/api/appointments/:id

Get appointment details

PATCH
/api/appointments/:id/status

Update appointment status

POST
/api/appointments/:id/reschedule

Reschedule

POST
/api/appointments/:id/cancel

Cancel

GET
/api/appointments/kanban

Kanban board view

Appointment Requests

GET
/api/appointment-requests

List pending requests

POST
/api/appointment-requests

Create a request

POST
/api/appointment-requests/:id/approve

Approve

POST
/api/appointment-requests/:id/reject

Reject

Telemedicine

POST
/api/appointments/:id/telemedicine/initiate

Start a video session

GET
/api/appointments/:id/telemedicine/status/:session_id

Get session status

POST
/api/appointments/:id/telemedicine/end/:session_id

End session

GET
/api/appointments/:id/telemedicine/:session_id/participants

List participants

Example: Book an Appointment

POST /api/appointments
Content-Type: application/json

{
  "resource_id": "doctor-resource-uuid",
  "patient_name": "Amara Okafor",
  "patient_email": "amara@example.com",
  "patient_phone": "+234801234567",
  "start_time": "2026-04-25T09:00:00Z",
  "end_time": "2026-04-25T09:30:00Z",
  "reason": "Annual checkup"
}

// 201 Created
{
  "success": true,
  "data": {
    "id": "appt-uuid",
    "status": "booked",
    ...
  }
}

Session Service

Clinical session recordings, AI-powered transcription, structured data extraction, clinical notes, and audit trails.

Recordings

GET
/api/sessions/recordings

List my recordings

POST
/api/sessions/recordings

Start a recording

GET
/api/sessions/recordings/:id

Get a recording

POST
/api/sessions/recordings/:id/audio

Upload audio

PATCH
/api/sessions/recordings/:id/ready

Mark recording ready

Transcription & Extraction

POST
/api/sessions/transcripts

Start AI transcription

PATCH
/api/sessions/transcripts/:id

Submit transcript

POST
/api/sessions/extractions

Start structured data extraction

GET
/api/sessions/extractions/:id

Get extraction result

POST
/api/sessions/extractions/:id/commit

Commit extraction to patient record

Clinical Notes

POST
/api/clinical/notes

Create a clinical note

GET
/api/clinical/notes/:id

Get a clinical note

PATCH
/api/clinical/notes/:id

Update a clinical note

POST
/api/clinical/notes/:id/sign

Sign/finalize a note

GET
/api/clinical/notes/patient/:patient_id

List patient notes

Action Items

GET
/api/sessions/action-items

List action items

POST
/api/sessions/action-items

Create action items

GET
/api/sessions/action-items/:id

Get an action item

PATCH
/api/sessions/action-items/:id

Update an action item

DELETE
/api/sessions/action-items/:id

Cancel an action item

Voice Dictation

POST
/api/clinical/dictation

Start dictation session

POST
/api/clinical/dictation/:id/segments

Add audio segment

POST
/api/clinical/dictation/:id/merge

Merge dictation into clinical note

Audit Events

POST
/api/clinical/audit

Log an audit event

GET
/api/clinical/audit/:id

Get audit event

GET
/api/clinical/audit/resource/:resource_type/:resource_id

Resource audit trail

GET
/api/clinical/audit/user/:user_id

User audit trail

GET
/api/clinical/audit/search

Search audit events

Clinical Decision Support (CDS)

Drug interactions, AI-powered diagnostics, risk scoring, early warning systems, and public health reporting.

Drug Interactions

POST
/api/cds/drug-interactions/check

Check for drug-drug interactions

POST
/api/cds/drug-interactions

Upsert interaction data (Admin)

AI-Powered Clinical Tools

POST
/api/ai/diagnosis

AI differential diagnosis

POST
/api/ai/lab-interpretation

AI lab result interpretation

POST
/api/ai/risk-stratification

Patient risk stratification

POST
/api/ai/cancer-detection

AI cancer detection analysis

POST
/api/ai/cloud-inference

General AI inference

Patient Safety

POST
/api/cds/early-warning-score

Calculate Early Warning Score (EWS)

POST
/api/cds/panic-values/check

Check for panic/critical lab values

GET
/api/cds/adverse-events

List adverse events

POST
/api/cds/adverse-events

Report an adverse event

GET
/api/cds/patient-risk

Get patient risk assessment

CDS Hooks (HL7 Standard)

GET
/cds-servicesPublic

CDS Hooks service discovery

POST
/cds-hooks/:hook_id

Invoke a CDS Hook

Public Health

GET
/api/public-health/dashboard

Public health dashboard (Admin)

POST
/api/public-health/cases

Report a notifiable case

GET
/api/public-health/dhis2-export

Export data for DHIS2

POST
/api/public-health/dhis2-push

Push data to DHIS2

Syndromic Surveillance

GET
/api/surveillance/syndromes

List monitored syndromes

GET
/api/surveillance/alerts

List surveillance alerts

POST
/api/surveillance/export/dhis2

Export surveillance to DHIS2

On-Device AI Models

GET
/api/ai/models

List registered AI models

POST
/api/ai/models

Register a model

GET
/api/ai/model-infoPublic

Get model metadata

GET
/api/ai/devices

List device model deployments

POST
/api/ai/devices/register

Register device model

POST
/api/ai/devices/:device_id/heartbeat

Device heartbeat

Example: Drug Interaction Check

POST /api/cds/drug-interactions/check
Authorization: Bearer v4.public.eyJ...
Content-Type: application/json

{
  "medications": [
    { "name": "Warfarin", "rxcui": "11289" },
    { "name": "Aspirin", "rxcui": "1191" }
  ]
}

// 200 OK
{
  "success": true,
  "data": {
    "interactions": [
      {
        "severity": "high",
        "description": "Concurrent use increases bleeding risk",
        "drugs": ["Warfarin", "Aspirin"],
        "recommendation": "Monitor INR closely; consider alternative antiplatelet"
      }
    ]
  }
}

Master Patient Index (MPI)

Patient identity matching, linking, and deduplication across organizations.

MPI access is restricted to platform administrators (SUPER:ADMIN, APP:ADMIN).

POST
/api/mpi/match

Find matching patients by demographics

GET
/api/mpi/patients/:id/fhir

Get FHIR Patient resource for a patient

GET
/api/mpi/links/:patient_id

List linked patient records

POST
/api/mpi/links

Create a patient link

GET
/api/mpi/candidates

List pending match candidates for review

PATCH
/api/mpi/links/:id/review

Review and approve/reject a match

GET
/api/mpi/matches

List all matches

GET
/api/mpi/matches/:id

Get a specific match

POST
/api/mpi/matches/:id/unlink

Unlink a patient match

POST
/api/mpi/link

Link two patients

Revenue Cycle Management (RCM)

Insurance claims, invoicing, eligibility verification, pre-authorization, fraud detection, and insurance marketplace.

Claims

GET
/api/rcm/claims

List claims

POST
/api/rcm/claims

Create a claim

GET
/api/rcm/claims/:id

Get claim details

PUT
/api/rcm/claims/:id

Update a claim

POST
/api/rcm/claims/:id/submit

Submit claim to insurer

POST
/api/rcm/claims/:id/eligibility

Check patient eligibility

POST
/api/rcm/claims/:id/preauth

Submit pre-authorization

Analytics & Fraud

GET
/api/rcm/claims/analytics/by-insurer

Claims analytics by insurer

GET
/api/rcm/claims/analytics/by-provider

Claims analytics by provider

GET
/api/rcm/claims/fraud-flags

List fraud flags

GET
/api/rcm/claims/reconciliation

Reconciliation report

Invoices

GET
/api/rcm/invoices

List RCM invoices

POST
/api/rcm/invoices

Create an invoice

GET
/api/rcm/invoices/:id

Get invoice details

Insurance Marketplace

GET
/api/rcm/marketplace/plans

List insurance plans

POST
/api/rcm/marketplace/enroll

Enroll in a plan

GET
/api/rcm/marketplace/policies

List active policies

Marketplace Service

Medical supply chain management: product catalog, orders, inventory, suppliers, and purchase orders.

Products & Catalog

GET
/api/marketplace/products

List products

POST
/api/marketplace/catalog/sync

Sync product catalog (Admin)

Orders

POST
/api/marketplace/orders

Create an order

GET
/api/marketplace/orders

List patient orders

GET
/api/marketplace/orders/:id

Get order details

DELETE
/api/marketplace/orders/:id

Cancel an order

POST
/api/marketplace/orders/:id/verify

Verify order

POST
/api/marketplace/orders/:id/transition

Transition order status

POST
/api/marketplace/cart/checkout

Checkout cart

Inventory

GET
/api/marketplace/inventory

List inventory

POST
/api/marketplace/inventory/sync

Sync inventory

GET
/api/marketplace/inventory/low-stock

Low stock alerts

POST
/api/marketplace/inventory/adjust

Adjust stock levels

Suppliers & Purchase Orders

GET
/api/marketplace/suppliers

List suppliers

POST
/api/marketplace/suppliers

Create supplier

GET
/api/marketplace/purchase-orders

List purchase orders

POST
/api/marketplace/purchase-orders

Create purchase order

POST
/api/marketplace/purchase-orders/:id/approve

Approve PO

Emergency

POST
/api/marketplace/emergency-routing

Emergency supply routing

POST
/api/marketplace/reorder-trigger

Automated reorder trigger

Workforce Service

Staff rostering, shift scheduling, fairness metrics, swap management, and capacity building.

Members & Shifts

GET
/api/workforce/members

List workforce members

POST
/api/workforce/members

Create a member

GET
/api/workforce/shift-types

List shift types

POST
/api/workforce/shift-types

Create a shift type

GET
/api/workforce/coverage-requirements

List coverage requirements

Rosters

GET
/api/workforce/rosters

List rosters

POST
/api/workforce/rosters

Create a roster

POST
/api/workforce/rosters/:id/generate

Auto-generate roster assignments

POST
/api/workforce/rosters/:id/approve

Approve a roster

POST
/api/workforce/rosters/:id/publish

Publish a roster

GET
/api/workforce/rosters/:id/coverage-gaps

Find coverage gaps

Swaps & Fairness

GET
/api/workforce/swaps

List swap requests

POST
/api/workforce/swaps

Create a swap request

POST
/api/workforce/swaps/:id/accept

Accept a swap

GET
/api/workforce/fairness

Organization fairness report

GET
/api/workforce/fairness/gini

Gini coefficient for shift distribution

Training & CME

GET
/api/training/courses

List training courses

POST
/api/training/courses

Create a course

POST
/api/training/courses/:id/enroll

Enroll in a course

GET
/api/training/enrollments

List enrollments

POST
/api/training/enrollments/:id/progress

Update progress

GET
/api/training/cme-credits

List CME credits

POST
/api/training/cme-credits

Award CME credit

GET
/api/training/cme-credits/summary

CME credit summary

GET
/api/training/assessments

List assessments

POST
/api/training/assessments

Create an assessment

Treatments Service

Treatment protocol definitions and tracking patient treatments.

GET
/api/treatments

List treatment protocols

POST
/api/treatments

Create a treatment protocol

GET
/api/treatments/:id

Get treatment details

PATCH
/api/treatments/:id

Update a treatment

DELETE
/api/treatments/:id

Delete a treatment

GET
/api/patients/:patient_id/treatments

List treatments for a patient

POST
/api/patient-treatments

Assign treatment to patient

PATCH
/api/patient-treatments/:id

Update patient treatment

Payments Service

Mobile money payment processing for M-Pesa, MTN MoMo, and Orange Money.

POST
/api/payments/mobile-money/initiate

Initiate a mobile money payment

GET
/api/payments/mobile-money/status/:order_id

Check payment status

Example: Initiate Payment

POST /api/payments/mobile-money/initiate
Authorization: Bearer v4.public.eyJ...
Content-Type: application/json

{
  "provider": "mpesa",
  "phone": "+254712345678",
  "amount": 1500.00,
  "currency": "KES",
  "order_id": "order-uuid",
  "description": "Consultation payment"
}

FHIR R4 Endpoints

Cross-border patient lookup via national Health Information Exchanges.

GET
/api/fhir/cross-border/Patient/:national_id?country=KE

Cross-border patient lookup via national HIE

GET
/.well-known/smart-configurationPublic

SMART on FHIR configuration discovery

POST
/api/smart/launch

SMART on FHIR app launch

Supported countries: KE (Kenya), GH (Ghana), NG (Nigeria), ZA (South Africa), TZ (Tanzania), UG (Uganda), RW (Rwanda), ET (Ethiopia).

Feedback Service

User feedback collection for authenticated and anonymous users.

POST
/api/feedback

Submit feedback (authenticated)

GET
/api/feedback

List feedback

GET
/api/feedback/:id

Get feedback

PATCH
/api/feedback/:id

Update feedback

POST
/api/feedback/anonymousPublic

Submit anonymous feedback

Related Documentation

Getting Started

Architecture and authentication

Integrations

FHIR, DHIS2, and HL7v2 guides

Webhooks

Real-time event notifications

SDKs & Libraries

Official TypeScript SDK

Getting StartedNext: Integrations