API Overview

The CPR backend exposes a RESTful JSON API under /api/v1. All endpoints require authentication via Laravel Sanctum unless noted otherwise.

Base URL

http://localhost:8000/api/v1     # Development
https://your-domain.com/api/v1   # Production

Required Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
X-Branch-Id: {branch_id}          # Required for branch-scoped routes

Response Format

Success Response

{
  "message": "Patient created successfully",
  "data": {
    "id": 1,
    "pin": "MAIN-000123",
    "first_name": "Juan",
    "last_name": "Dela Cruz"
  }
}

Paginated Response

{
  "data": [...],
  "links": {
    "first": "/api/v1/patients?page=1",
    "last": "/api/v1/patients?page=5",
    "prev": null,
    "next": "/api/v1/patients?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 15,
    "to": 15,
    "total": 72
  }
}

Error Response

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email must be a valid email address."]
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Resource created
400	Missing branch context
401	Unauthenticated (invalid/missing token)
403	Forbidden (no permission or branch access)
404	Resource not found
422	Validation errors
429	Rate limit exceeded
500	Server error

Endpoint Groups

Public (No Auth Required)

Method	Endpoint	Description
GET	/public/health	Health check

Authentication

Method	Endpoint	Description
POST	/auth/login	Login
POST	/auth/logout	Logout
GET	/auth/profile	Get profile
PUT	/auth/profile	Update profile
POST	/auth/switch-branch	Switch branch
GET	/auth/branches	List user's branches
POST	/auth/reset-code	Request reset code
POST	/auth/verify-code	Verify reset code
POST	/auth/reset-password	Reset password

Branch-Scoped Routes (Require X-Branch-Id header)

Patient Management

Method	Endpoint	Description
GET	/patients	List patients (paginated, searchable)
POST	/patients	Create patient
GET	/patients/search	Search patients
GET	/patients/export	Export patients
GET	/patients/{id}	Get patient
PUT	/patients/{id}	Update patient
DELETE	/patients/{id}	Delete patient
GET	/patient-visits	List visits
POST	/patient-visits	Create visit
GET/PUT/DELETE	/patient-visits/{id}	CRUD visit
GET/POST/PUT/DELETE	/patient-visit-plans/{id}	CRUD visit plans
GET/POST/PUT/DELETE	/patient-visit-prescribed-medicines/{id}	CRUD prescriptions
GET/POST/PUT/DELETE	/complaints/{id}	CRUD complaints
GET/POST/PUT/DELETE	/medical-certificates/{id}	CRUD certificates

Clinical Examinations (all CRUD)

Endpoint	Exam Type
/visual-acuities	Visual Acuity
/refractions	Refraction
/tonometries	Tonometry
/slit-lamps	Slit Lamp
/funduscopies	Funduscopy
/gonioscopies	Gonioscopy
/corneal-topographies	Corneal Topography
/amsler-grids	Amsler Grid
/eoms	Extraocular Muscles
/exophthalmometries	Exophthalmometry
/lacrimal-irrigations	Lacrimal Irrigation
/radiologies	Radiology
/gross-examinations	Gross Examination
/indirect-ophthalmoscopies	Indirect Ophthalmoscopy

Billing & Queue

Method	Endpoint	Description
GET/POST	/patients/{id}/billing-transactions	Patient billing
GET/PUT/DELETE	/patients/{id}/billing-transactions/{txn}	Manage transaction
POST	/queue/visits	Create queue visit
GET	/queue/branch-services/{id}/queue	Get service queue
POST	/queue/branch-services/{id}/queue	Create queue ticket
PUT	/queue/queue-tickets/{id}/call	Call ticket
PUT	/queue/queue-tickets/{id}/serve	Serve ticket
PUT	/queue/queue-tickets/{id}/complete	Complete ticket
PUT	/queue/queue-tickets/{id}/skip	Skip ticket
PUT	/queue/queue-tickets/{id}/no-show	Mark no-show
POST	/queue/queue-tickets/{id}/transfer	Transfer ticket

Dashboard

Method	Endpoint	Description
GET	/dashboard/stats	Dashboard statistics
GET	/dashboard/calendar	Calendar data
GET	/dashboard/patient-flow	Patient flow metrics
GET	/dashboard/upcoming-surgeries	Upcoming surgeries
GET	/dashboard/patient-demographics	Demographics

Global Routes (Auth required, no branch context)

Master Data (all CRUD)

Endpoint	Description
/bill-items	Billable items
/medicines	Medicine reference
/procedures	Medical procedures
/insurances	Insurance plans
/services	Clinical services
/doctors	Doctor profiles
/surgery-schedules	Surgery scheduling

Pharmacy & Inventory (all CRUD)

Endpoint	Description
/pharmacy-items	Pharmacy products
/stock-availables	Stock levels
/stock-movements	Stock tracking
/purchase-orders	Purchase orders
/transactions	Pharmacy transactions
/deliveries	Delivery records

Read-Only Lookups

Endpoint	Description
/bill-item-categories	Bill categories
/payment-methods	Payment methods
/suppliers	Suppliers
/purchase-order-statuses	PO statuses
/enums	Enum definitions

Admin Routes (Require admin.access permission)

Method	Endpoint	Description
GET/POST	/branches	List/create branches
GET/PUT/DELETE	/branches/{id}	Manage branch
GET/POST	/branches/{id}/services	Branch services
GET/PUT/DELETE	/branches/{id}/services/{svc}	Manage service
POST	/branches/{id}/services/{svc}/staff	Assign staff
DELETE	/branches/{id}/services/{svc}/staff/{user}	Remove staff
GET/POST/PUT/DELETE	/roles	Role management

Toggle Status Pattern

Several resources support a status toggle endpoint:

PATCH /api/v1/medicines/{id}/toggle-status
PATCH /api/v1/procedures/{id}/toggle-status
PATCH /api/v1/insurances/{id}/toggle-status
PATCH /api/v1/pharmacy-items/{id}/toggle-status
PATCH /api/v1/services/{id}/toggle-status

Auto-Generated API Docs

The project uses Dedoc Scramble to auto-generate OpenAPI documentation from the codebase. Access it at:

http://localhost:8000/docs/api