Visits

Visit endpoints manage clinical visit records for patients. Each visit contains hormone biomarkers, symptom assessments, medication information, and lifestyle data collected during a healthcare provider encounter.

Create Visit

Create a new visit record for a patient.

Endpoint: POST /visits

Authentication: Required (provider, admin role)

Request

{
  "patient_id": "pat_a1b2c3d4e5f6",
  "visit_date": "2024-02-15",
  "visit_type": "initial_consultation",
  "hormone_biomarkers": {
    "fsh_miu_ml": 45.2,
    "lh_miu_ml": 28.5,
    "estradiol_pg_ml": 32.1,
    "progesterone_ng_ml": 0.5,
    "testosterone_ng_dl": 28
  },
  "symptoms": {
    "hot_flashes": "moderate",
    "night_sweats": "mild",
    "vaginal_dryness": "severe",
    "mood_changes": "mild",
    "sleep_disturbance": "moderate",
    "joint_pain": "none",
    "brain_fog": "mild"
  },
  "medications": [
    {
      "name": "Hormone Replacement Therapy",
      "type": "estrogen_progestin",
      "dosage": "0.5mg",
      "frequency": "daily",
      "start_date": "2024-02-01"
    },
    {
      "name": "Vitamin D3",
      "type": "supplement",
      "dosage": "2000 IU",
      "frequency": "daily"
    }
  ],
  "lifestyle": {
    "exercise_minutes_per_week": 120,
    "sleep_hours_per_night": 7,
    "alcohol_units_per_week": 5,
    "stress_level": "moderate"
  },
  "provider_notes": "Patient reports significant improvement in hot flash frequency. Continue current treatment plan."
}

Request Schema

VisitInput

Field	Type	Required	Description
patient_id	string	Yes	De-identified patient ID (pat_*)
visit_date	string (YYYY-MM-DD)	Yes	Date of clinical visit
visit_type	string	Yes	Type: `initial_consultation`, `follow_up`, `annual_checkup`, `emergency`
hormone_biomarkers	object	No	Hormone levels measured during visit
symptoms	object	No	Menopause symptom severity assessment
medications	array	No	List of medications/supplements
lifestyle	object	No	Lifestyle factors and habits
provider_notes	string	No	Provider clinical notes (max 1000 characters)

Hormone Biomarkers Schema

Field	Type	Range	Description
fsh_miu_ml	number	0-300	Follicle-Stimulating Hormone (mIU/ml)
lh_miu_ml	number	0-200	Luteinizing Hormone (mIU/ml)
estradiol_pg_ml	number	0-1000	Estradiol (pg/ml)
progesterone_ng_ml	number	0-100	Progesterone (ng/ml)
testosterone_ng_dl	number	0-300	Testosterone (ng/dL)

Symptoms Schema

Field	Type	Valid Values	Description
hot_flashes	string	`none`, `mild`, `moderate`, `severe`	Frequency/severity
night_sweats	string	`none`, `mild`, `moderate`, `severe`	Frequency/severity
vaginal_dryness	string	`none`, `mild`, `moderate`, `severe`	Severity
mood_changes	string	`none`, `mild`, `moderate`, `severe`	Severity
sleep_disturbance	string	`none`, `mild`, `moderate`, `severe`	Severity
joint_pain	string	`none`, `mild`, `moderate`, `severe`	Severity
brain_fog	string	`none`, `mild`, `moderate`, `severe`	Severity

Medications Schema

Field	Type	Required	Description
name	string	Yes	Medication/supplement name
type	string	Yes	Category: `estrogen`, `progestin`, `estrogen_progestin`, `serotonin_antagonist`, `selective_serotonin_reuptake_inhibitor`, `supplement`, `other`
dosage	string	No	Dosage amount and unit
frequency	string	No	`once_daily`, `twice_daily`, `three_times_daily`, `as_needed`, `weekly`, etc.
start_date	string (YYYY-MM-DD)	No	Treatment start date
end_date	string (YYYY-MM-DD)	No	Treatment end date (if discontinued)

Lifestyle Schema

Field	Type	Range	Description
exercise_minutes_per_week	integer	0-1000	Minutes of moderate exercise per week
sleep_hours_per_night	number	0-12	Average hours of sleep per night
alcohol_units_per_week	number	0-100	Standard alcoholic drinks per week
stress_level	string	`low`, `moderate`, `high`	Subjective stress assessment

Response (201 Created)

{
  "status": "success",
  "data": {
    "id": "vis_x1y2z3a4b5c6",
    "patient_id": "pat_a1b2c3d4e5f6",
    "visit_date": "2024-02-15",
    "visit_type": "initial_consultation",
    "hormone_biomarkers": {
      "fsh_miu_ml": 45.2,
      "lh_miu_ml": 28.5,
      "estradiol_pg_ml": 32.1,
      "progesterone_ng_ml": 0.5,
      "testosterone_ng_dl": 28
    },
    "symptoms": {
      "hot_flashes": "moderate",
      "night_sweats": "mild",
      "vaginal_dryness": "severe",
      "mood_changes": "mild",
      "sleep_disturbance": "moderate",
      "joint_pain": "none",
      "brain_fog": "mild"
    },
    "medications": [
      {
        "id": "med_d7e8f9g0h1i2",
        "name": "Hormone Replacement Therapy",
        "type": "estrogen_progestin",
        "dosage": "0.5mg",
        "frequency": "daily",
        "start_date": "2024-02-01"
      },
      {
        "id": "med_j3k4l5m6n7o8",
        "name": "Vitamin D3",
        "type": "supplement",
        "dosage": "2000 IU",
        "frequency": "daily"
      }
    ],
    "lifestyle": {
      "exercise_minutes_per_week": 120,
      "sleep_hours_per_night": 7,
      "alcohol_units_per_week": 5,
      "stress_level": "moderate"
    },
    "provider_notes": "Patient reports significant improvement in hot flash frequency. Continue current treatment plan.",
    "created_at": "2024-02-15T14:35:00Z",
    "updated_at": "2024-02-15T14:35:00Z"
  }
}

Example Using cURL

curl -X POST https://api.menotime.timelessbiotech.com/v1/visits \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "pat_a1b2c3d4e5f6",
    "visit_date": "2024-02-15",
    "visit_type": "initial_consultation",
    "hormone_biomarkers": {
      "fsh_miu_ml": 45.2,
      "lh_miu_ml": 28.5,
      "estradiol_pg_ml": 32.1
    },
    "symptoms": {
      "hot_flashes": "moderate",
      "vaginal_dryness": "severe"
    },
    "provider_notes": "Initial assessment complete."
  }'

Example Using Python

import requests
from datetime import date

headers = {"Authorization": f"Bearer {access_token}"}

visit_data = {
    "patient_id": "pat_a1b2c3d4e5f6",
    "visit_date": str(date.today()),
    "visit_type": "follow_up",
    "hormone_biomarkers": {
        "fsh_miu_ml": 45.2,
        "lh_miu_ml": 28.5,
        "estradiol_pg_ml": 32.1
    },
    "symptoms": {
        "hot_flashes": "moderate",
        "vaginal_dryness": "severe"
    }
}

response = requests.post(
    "https://api.menotime.timelessbiotech.com/v1/visits",
    json=visit_data,
    headers=headers
)

visit = response.json()["data"]
print(f"Created visit: {visit['id']}")

List Visits

Retrieve a paginated list of visit records.

Endpoint: GET /visits

Authentication: Required (provider, readonly, admin role)

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number for pagination
limit	integer	20	Records per page (1-100)
patient_id	string	None	Filter by patient ID
visit_type	string	None	Filter by visit type
start_date	string (YYYY-MM-DD)	None	Filter from date
end_date	string (YYYY-MM-DD)	None	Filter to date

Response (200 OK)

{
  "status": "success",
  "data": [
    {
      "id": "vis_x1y2z3a4b5c6",
      "patient_id": "pat_a1b2c3d4e5f6",
      "visit_date": "2024-02-15",
      "visit_type": "initial_consultation",
      "hormone_biomarkers": {
        "fsh_miu_ml": 45.2,
        "lh_miu_ml": 28.5,
        "estradiol_pg_ml": 32.1,
        "progesterone_ng_ml": 0.5,
        "testosterone_ng_dl": 28
      },
      "symptoms": {
        "hot_flashes": "moderate",
        "night_sweats": "mild",
        "vaginal_dryness": "severe",
        "mood_changes": "mild",
        "sleep_disturbance": "moderate",
        "joint_pain": "none",
        "brain_fog": "mild"
      },
      "created_at": "2024-02-15T14:35:00Z"
    },
    {
      "id": "vis_p9q0r1s2t3u4",
      "patient_id": "pat_a1b2c3d4e5f6",
      "visit_date": "2024-02-08",
      "visit_type": "follow_up",
      "hormone_biomarkers": {
        "fsh_miu_ml": 48.1,
        "lh_miu_ml": 30.2,
        "estradiol_pg_ml": 28.9
      },
      "symptoms": {
        "hot_flashes": "moderate",
        "vaginal_dryness": "severe"
      },
      "created_at": "2024-02-08T10:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 342,
    "pages": 18
  }
}

Example Using cURL

curl -X GET "https://api.menotime.timelessbiotech.com/v1/visits?patient_id=pat_a1b2c3d4e5f6&limit=10" \
  -H "Authorization: Bearer {access_token}"

Get Visit

Retrieve a single visit record by ID.

Endpoint: GET /visits/{id}

Authentication: Required (provider, readonly, admin role)

Path Parameters

Parameter	Type	Description
id	string	Visit ID (vis_*)

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": "vis_x1y2z3a4b5c6",
    "patient_id": "pat_a1b2c3d4e5f6",
    "visit_date": "2024-02-15",
    "visit_type": "initial_consultation",
    "hormone_biomarkers": {
      "fsh_miu_ml": 45.2,
      "lh_miu_ml": 28.5,
      "estradiol_pg_ml": 32.1,
      "progesterone_ng_ml": 0.5,
      "testosterone_ng_dl": 28
    },
    "symptoms": {
      "hot_flashes": "moderate",
      "night_sweats": "mild",
      "vaginal_dryness": "severe",
      "mood_changes": "mild",
      "sleep_disturbance": "moderate",
      "joint_pain": "none",
      "brain_fog": "mild"
    },
    "medications": [
      {
        "id": "med_d7e8f9g0h1i2",
        "name": "Hormone Replacement Therapy",
        "type": "estrogen_progestin",
        "dosage": "0.5mg",
        "frequency": "daily",
        "start_date": "2024-02-01"
      }
    ],
    "lifestyle": {
      "exercise_minutes_per_week": 120,
      "sleep_hours_per_night": 7,
      "alcohol_units_per_week": 5,
      "stress_level": "moderate"
    },
    "provider_notes": "Patient reports significant improvement in hot flash frequency. Continue current treatment plan.",
    "created_at": "2024-02-15T14:35:00Z",
    "updated_at": "2024-02-15T14:35:00Z"
  }
}

Example Using cURL

curl -X GET https://api.menotime.timelessbiotech.com/v1/visits/vis_x1y2z3a4b5c6 \
  -H "Authorization: Bearer {access_token}"

Update Visit

Update an existing visit record.

Endpoint: PUT /visits/{id}

Authentication: Required (provider, admin role)

Request

{
  "symptoms": {
    "hot_flashes": "mild",
    "night_sweats": "none",
    "vaginal_dryness": "moderate"
  },
  "provider_notes": "Patient reports improvement after 2 weeks on HRT."
}

Updatable Fields

Field	Type	Description
hormone_biomarkers	object	Hormone levels
symptoms	object	Symptom severity assessments
medications	array	List of medications
lifestyle	object	Lifestyle factors
provider_notes	string	Clinical notes

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": "vis_x1y2z3a4b5c6",
    "patient_id": "pat_a1b2c3d4e5f6",
    "visit_date": "2024-02-15",
    "visit_type": "initial_consultation",
    "symptoms": {
      "hot_flashes": "mild",
      "night_sweats": "none",
      "vaginal_dryness": "moderate",
      "mood_changes": "mild",
      "sleep_disturbance": "moderate",
      "joint_pain": "none",
      "brain_fog": "mild"
    },
    "provider_notes": "Patient reports improvement after 2 weeks on HRT.",
    "updated_at": "2024-02-18T09:15:00Z"
  }
}

Linking Visits to Patients

Each visit record maintains a reference to its patient via the patient_id field. This relationship allows you to:

Retrieve All Visits for a Patient

curl -X GET "https://api.menotime.timelessbiotech.com/v1/visits?patient_id=pat_a1b2c3d4e5f6" \
  -H "Authorization: Bearer {access_token}"

Access Visit Information When Retrieving Patient Details

When you retrieve a patient record with GET /patients/{id}, the response includes a summary of recent visits:

{
  "status": "success",
  "data": {
    "id": "pat_a1b2c3d4e5f6",
    "age_years": 52,
    "visits": [
      {
        "id": "vis_x1y2z3a4b5c6",
        "visit_date": "2024-02-15",
        "visit_type": "initial_consultation",
        "created_at": "2024-02-15T14:35:00Z"
      }
    ]
  }
}

Validation Rules

Date Validation

visit_date: Must not be in the future
visit_date: Must be in YYYY-MM-DD format

Hormone Biomarker Ranges

All hormone values must fall within physiologically reasonable ranges:

fsh_miu_ml: 0-300
lh_miu_ml: 0-200
estradiol_pg_ml: 0-1000
progesterone_ng_ml: 0-100
testosterone_ng_dl: 0-300

Lifestyle Field Ranges

exercise_minutes_per_week: 0-1000
sleep_hours_per_night: 0-12 (typically 7-9 is normal)
alcohol_units_per_week: 0-100
Standard drink = 5 oz wine, 12 oz beer, or 1.5 oz spirits

Provider Notes

Maximum 1000 characters
Plain text only

Error Examples

Patient Not Found

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "Patient not found",
  "details": {
    "patient_id": "pat_invalid"
  }
}

Invalid Hormone Value

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": [
    {
      "field": "hormone_biomarkers.fsh_miu_ml",
      "message": "Value must be between 0 and 300"
    }
  ]
}

Invalid Symptom Severity

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": [
    {
      "field": "symptoms.hot_flashes",
      "message": "Invalid value 'extreme'. Valid values: none, mild, moderate, severe"
    }
  ]
}