A Django REST Framework API for a home health agency: caregiver and patient records, visit scheduling with task checklists, medication tracking, a GeoDjango-backed caregiver-matching engine, geofenced mobile check-in/check-out with vitals and ADL capture, caregiver payroll, billing and A/R with payer scorecard reporting, caregiver productivity reporting, and office-to-caregiver messaging with push notifications.
Every area below is fully documented (fields, choices, request/response shapes) in Swagger — this page covers the why and the recommended flow.
Full CRUD for caregiver and patient profiles plus their lookup tables — certifications, skills, languages, ADL definitions, medications, insurance, emergency contacts, and more.
/api/caregiver/*
/api/patient/*
Ranks qualifying caregivers for a patient by proximity, availability, and preference fit. Hard filters (active, territory, availability overlap) run first; a transparent 5-factor, 100-point score ranks the rest. Race, ethnicity, and nationality are deliberately excluded from scoring.
GET /api/scheduling/patients/<id>/match-caregivers/
Turns a scheduled visit into a GPS-verified worked shift. Idempotent via a client-generated event id; out-of-geofence readings are soft-flagged, never hard-blocked, and held out of payroll until staff review.
POST /api/scheduling/visits/<id>/check-in/
POST /api/scheduling/visits/<id>/check-out/
POST /api/scheduling/visits/<id>/review-geofence/
Structured vitals readings and ADL-performed outcomes logged against a visit, separate from the freeform task checklist. Abnormal vitals are flagged automatically.
/api/scheduling/vitals/
/api/scheduling/visit-adl-results/
System-of-record for hours worked and gross pay: caregiver pay rates, per-caregiver timesheets with an approve/adjust/dispute workflow, and a CSV export for an external payroll processor.
/api/payroll/pay-rates/
/api/payroll/pay-periods/
/api/payroll/timesheets/
/api/payroll/timesheet-entries/
System-of-record for charges, claims, and payments — not a clearinghouse. Charges generate from completed visits, bundle into claims, and export as CSV; payments/denials/appeals resolve A/R, tracked via an aging report and a per-payer scorecard.
/api/billing/charges/
/api/billing/claims/
/api/billing/payments/
/api/billing/ar-aging/
/api/billing/payer-scorecard/
Cross-visit caregiver productivity metrics — no data model of its own, purely aggregation over existing scheduling/payroll data (visits, tasks, vitals, ADLs, check events, timesheets, match-log shortlists).
GET /api/reporting/caregiver-productivity/
Office-to-caregiver chat over plain REST + polling, with Firebase push notifications on every new message so clients don’t need to poll aggressively.
/api/messaging/conversations/
/api/messaging/messages/
/api/auth/device-tokens/
Stateless JWT (djangorestframework-simplejwt) — a Bearer token, not
cookies/sessions. Every endpoint except the token endpoint requires it.
POST /api/auth/token/ with a
username/password, get back a 30-minute access and a 14-day
refresh token.Authorization: Bearer <access> on
every request. Refresh via POST /api/auth/token/refresh/ when it expires.GET /api/auth/me/ returns your
profile, groups, and derived role (caregiver / patient / staff).POST /api/auth/token/
Content-Type: application/json
{"username": "danielle.johnson", "password": "TestPass123!"}
→ {"refresh": "eyJhbGci...", "access": "eyJhbGci..."}
GET /api/caregiver/caregivers/
Authorization: Bearer <access>No client needed to try it live — Swagger UI at /api/docs/ has its own "Authorize" button that applies a Bearer token to every "Try it out" call on the page.
Deep-dive documentation for the less obvious parts of the system.