API Endpoints Reference

Complete reference for all SecureHealth API endpoints, including request/response formats, authentication requirements, and error codes.

Base URL

https://api.securehealth.dev/v1

Authentication

All API requests require a valid JWT token:

Authorization: Bearer <jwt_token>

Patient Endpoints

List Patients

GET /patients

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 20)
search (optional): Search term
role (optional): Filter by role

Response:

{
  "data": [
    {
      "id": "patient_123",
      "patientId": "PAT-12345",
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-05-15",
      "email": "john.doe@email.com",
      "phone": "+1-555-123-4567"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Get Patient Details

GET /patients/{id}

Response:

{
  "id": "patient_123",
  "patientId": "PAT-12345",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "email": "john.doe@email.com",
  "phone": "+1-555-123-4567",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zipCode": "12345"
  },
  "medicalHistory": "Patient has diabetes...",
  "labResults": [
    {
      "testDate": "2024-01-15",
      "testType": "Blood Glucose",
      "result": "150 mg/dL",
      "normalRange": "70-100 mg/dL"
    }
  ],
  "prescriptions": [
    {
      "medication": "Metformin",
      "dosage": "500mg",
      "frequency": "Twice daily",
      "startDate": "2024-01-01",
      "endDate": "2024-12-31"
    }
  ],
  "appointments": [
    {
      "date": "2024-01-15",
      "doctor": "Dr. Smith",
      "type": "Follow-up",
      "notes": "Regular checkup"
    }
  ]
}

Create Patient

POST /patients

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "email": "john.doe@email.com",
  "phone": "+1-555-123-4567",
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zipCode": "12345"
  },
  "insurance": {
    "provider": "Blue Cross",
    "policyNumber": "BC123456789",
    "groupNumber": "GRP001"
  }
}

Response:

{
  "id": "patient_123",
  "patientId": "PAT-12345",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-15",
  "email": "john.doe@email.com",
  "phone": "+1-555-123-4567",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Update Patient

PUT /patients/{id}

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@newemail.com",
  "phone": "+1-555-987-6543",
  "address": {
    "street": "456 Oak Ave",
    "city": "Newtown",
    "state": "CA",
    "zipCode": "54321"
  }
}

Response:

{
  "id": "patient_123",
  "patientId": "PAT-12345",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@newemail.com",
  "phone": "+1-555-987-6543",
  "address": {
    "street": "456 Oak Ave",
    "city": "Newtown",
    "state": "CA",
    "zipCode": "54321"
  },
  "updatedAt": "2024-01-15T11:00:00Z"
}

Delete Patient

DELETE /patients/{id}

Response:

{
  "message": "Patient deleted successfully"
}

Medical Records Endpoints

Get Medical History

GET /patients/{id}/medical-history

Response:

{
  "medicalHistory": "Patient has diabetes type 2, diagnosed in 2020. Currently managed with Metformin. No known allergies. Family history of diabetes.",
  "diagnoses": [
    {
      "condition": "Diabetes Type 2",
      "diagnosedDate": "2020-03-15",
      "status": "Active",
      "notes": "Well controlled with medication"
    }
  ],
  "allergies": [
    {
      "allergen": "Penicillin",
      "reaction": "Rash",
      "severity": "Moderate"
    }
  ]
}

Update Medical History

PUT /patients/{id}/medical-history

Request Body:

{
  "medicalHistory": "Patient has diabetes type 2, diagnosed in 2020. Currently managed with Metformin and diet. No known allergies. Family history of diabetes.",
  "diagnoses": [
    {
      "condition": "Diabetes Type 2",
      "diagnosedDate": "2020-03-15",
      "status": "Active",
      "notes": "Well controlled with medication and diet"
    }
  ]
}

Response:

{
  "message": "Medical history updated successfully",
  "updatedAt": "2024-01-15T11:30:00Z"
}

Get Lab Results

GET /patients/{id}/lab-results

Query Parameters:

startDate (optional): Start date for results
endDate (optional): End date for results
testType (optional): Filter by test type

Response:

{
  "labResults": [
    {
      "id": "lab_123",
      "testDate": "2024-01-15",
      "testType": "Blood Glucose",
      "result": "150 mg/dL",
      "normalRange": "70-100 mg/dL",
      "status": "High",
      "notes": "Patient fasting"
    },
    {
      "id": "lab_124",
      "testDate": "2024-01-15",
      "testType": "HbA1c",
      "result": "7.2%",
      "normalRange": "<7.0%",
      "status": "High",
      "notes": "3-month average"
    }
  ]
}

Add Lab Result

POST /patients/{id}/lab-results

Request Body:

{
  "testDate": "2024-01-15",
  "testType": "Blood Glucose",
  "result": "150 mg/dL",
  "normalRange": "70-100 mg/dL",
  "status": "High",
  "notes": "Patient fasting"
}

Response:

{
  "id": "lab_125",
  "testDate": "2024-01-15",
  "testType": "Blood Glucose",
  "result": "150 mg/dL",
  "normalRange": "70-100 mg/dL",
  "status": "High",
  "notes": "Patient fasting",
  "createdAt": "2024-01-15T12:00:00Z"
}

Prescription Endpoints

Get Prescriptions

GET /patients/{id}/prescriptions

Query Parameters:

status (optional): Filter by status (active, inactive, all)

Response:

{
  "prescriptions": [
    {
      "id": "prescription_123",
      "medication": "Metformin",
      "dosage": "500mg",
      "frequency": "Twice daily",
      "startDate": "2024-01-01",
      "endDate": "2024-12-31",
      "status": "Active",
      "prescribedBy": "Dr. Smith",
      "pharmacy": "CVS Pharmacy"
    }
  ]
}

Create Prescription

POST /patients/{id}/prescriptions

Request Body:

{
  "medication": "Metformin",
  "dosage": "500mg",
  "frequency": "Twice daily",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "pharmacy": "CVS Pharmacy",
  "instructions": "Take with food"
}

Response:

{
  "id": "prescription_124",
  "medication": "Metformin",
  "dosage": "500mg",
  "frequency": "Twice daily",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "status": "Active",
  "prescribedBy": "Dr. Smith",
  "pharmacy": "CVS Pharmacy",
  "instructions": "Take with food",
  "createdAt": "2024-01-15T12:30:00Z"
}

Update Prescription

PUT /prescriptions/{id}

Request Body:

{
  "dosage": "1000mg",
  "frequency": "Twice daily",
  "instructions": "Take with food, monitor blood sugar"
}

Response:

{
  "id": "prescription_124",
  "medication": "Metformin",
  "dosage": "1000mg",
  "frequency": "Twice daily",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "status": "Active",
  "prescribedBy": "Dr. Smith",
  "pharmacy": "CVS Pharmacy",
  "instructions": "Take with food, monitor blood sugar",
  "updatedAt": "2024-01-15T13:00:00Z"
}

Appointment Endpoints

List Appointments

GET /appointments

Query Parameters:

patientId (optional): Filter by patient ID
doctorId (optional): Filter by doctor ID
startDate (optional): Start date for appointments
endDate (optional): End date for appointments
status (optional): Filter by status (scheduled, completed, cancelled)

Response:

{
  "appointments": [
    {
      "id": "appointment_123",
      "patientId": "patient_123",
      "patientName": "John Doe",
      "doctorId": "doctor_456",
      "doctorName": "Dr. Smith",
      "date": "2024-01-15",
      "time": "10:00",
      "type": "Follow-up",
      "status": "Scheduled",
      "notes": "Regular checkup"
    }
  ]
}

Create Appointment

POST /appointments

Request Body:

{
  "patientId": "patient_123",
  "doctorId": "doctor_456",
  "date": "2024-01-20",
  "time": "14:00",
  "type": "Follow-up",
  "notes": "Regular checkup"
}

Response:

{
  "id": "appointment_124",
  "patientId": "patient_123",
  "patientName": "John Doe",
  "doctorId": "doctor_456",
  "doctorName": "Dr. Smith",
  "date": "2024-01-20",
  "time": "14:00",
  "type": "Follow-up",
  "status": "Scheduled",
  "notes": "Regular checkup",
  "createdAt": "2024-01-15T13:30:00Z"
}

Update Appointment

PUT /appointments/{id}

Request Body:

{
  "date": "2024-01-21",
  "time": "15:00",
  "notes": "Rescheduled due to conflict"
}

Response:

{
  "id": "appointment_124",
  "patientId": "patient_123",
  "patientName": "John Doe",
  "doctorId": "doctor_456",
  "doctorName": "Dr. Smith",
  "date": "2024-01-21",
  "time": "15:00",
  "type": "Follow-up",
  "status": "Scheduled",
  "notes": "Rescheduled due to conflict",
  "updatedAt": "2024-01-15T14:00:00Z"
}

Cancel Appointment

DELETE /appointments/{id}

Response:

{
  "message": "Appointment cancelled successfully"
}

User Management Endpoints

List Users

GET /users

Query Parameters:

role (optional): Filter by role
status (optional): Filter by status (active, inactive)

Response:

{
  "users": [
    {
      "id": "user_123",
      "email": "doctor@securehealth.dev",
      "firstName": "Dr. Jane",
      "lastName": "Smith",
      "roles": ["ROLE_DOCTOR"],
      "department": "Cardiology",
      "isActive": true,
      "lastLogin": "2024-01-15T10:30:00Z"
    }
  ]
}

Create User

POST /users

Request Body:

{
  "email": "nurse@securehealth.dev",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "roles": ["ROLE_NURSE"],
  "department": "Cardiology",
  "password": "securepassword123"
}

Response:

{
  "id": "user_124",
  "email": "nurse@securehealth.dev",
  "firstName": "Sarah",
  "lastName": "Johnson",
  "roles": ["ROLE_NURSE"],
  "department": "Cardiology",
  "isActive": true,
  "createdAt": "2024-01-15T14:30:00Z"
}

Audit Logs Endpoints

Get Audit Logs

GET /audit-logs

Query Parameters:

userId (optional): Filter by user ID
action (optional): Filter by action
startDate (optional): Start date for logs
endDate (optional): End date for logs
resourceType (optional): Filter by resource type

Response:

{
  "auditLogs": [
    {
      "id": "audit_123",
      "timestamp": "2024-01-15T10:30:00Z",
      "user": {
        "id": "user_123",
        "email": "doctor@securehealth.dev",
        "role": "ROLE_DOCTOR"
      },
      "action": "VIEW_PATIENT",
      "resource": {
        "type": "Patient",
        "id": "patient_123",
        "patientId": "PAT-12345"
      },
      "result": "SUCCESS",
      "ipAddress": "192.168.1.100"
    }
  ]
}

Error Codes

HTTP Status Codes

200 OK: Request successful
201 Created: Resource created successfully
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "message": "Invalid email format"
    }
  }
}

Rate Limiting

Rate Limits

Authentication: 5 requests per minute
General API: 100 requests per minute
Patient Data: 50 requests per minute
Audit Logs: 20 requests per minute

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

Next Steps

Configuration Reference - All configuration options
Environment Variables - Environment setup
Troubleshooting - Common issues and solutions
Glossary - Technical terms and definitions

Base URL​

Authentication​

Patient Endpoints​

List Patients​

Get Patient Details​

Create Patient​

Update Patient​

Delete Patient​

Medical Records Endpoints​

Get Medical History​

Update Medical History​

Get Lab Results​

Add Lab Result​

Prescription Endpoints​

Get Prescriptions​

Create Prescription​

Update Prescription​

Appointment Endpoints​

List Appointments​

Create Appointment​

Update Appointment​

Cancel Appointment​

User Management Endpoints​

List Users​

Create User​

Audit Logs Endpoints​

Get Audit Logs​

Error Codes​

HTTP Status Codes​

Error Response Format​

Rate Limiting​

Rate Limits​

Rate Limit Headers​

Next Steps​

Base URL

Authentication

Patient Endpoints

List Patients

Get Patient Details

Create Patient

Update Patient

Delete Patient

Medical Records Endpoints

Get Medical History

Update Medical History

Get Lab Results

Add Lab Result

Prescription Endpoints

Get Prescriptions

Create Prescription

Update Prescription

Appointment Endpoints

List Appointments

Create Appointment

Update Appointment

Cancel Appointment

User Management Endpoints

List Users

Create User

Audit Logs Endpoints

Get Audit Logs

Error Codes

HTTP Status Codes

Error Response Format

Rate Limiting

Rate Limits

Rate Limit Headers

Next Steps