Patients

Patient endpoints manage de-identified patient records. All patient data is collected from healthcare providers and de-identified according to HIPAA Safe Harbor standards before storage.

Create Patient

Create a new de-identified patient record.

Endpoint: POST /patients

Authentication: Required (provider, admin role)

Request

{
  "age_years": 52,
  "age_months": 0,
  "race": "caucasian",
  "ethnicity": "non_hispanic",
  "region": "northeast",
  "menopause_status": "perimenopause",
  "bmi": 26.5,
  "smoker": false,
  "hypertension": false,
  "diabetes": false,
  "family_history_breast_cancer": false,
  "notes": "Initial patient intake"
}

Request Schema

PatientInput (schema for POST requests)

Field	Type	Required	Description
age_years	integer	Yes	Patient age in years (18-120)
age_months	integer	No	Additional months (0-11)
race	string	Yes	Race category: `caucasian`, `african_american`, `asian`, `hispanic`, `native_american`, `pacific_islander`, `other`, `unknown`
ethnicity	string	Yes	Ethnicity: `hispanic`, `non_hispanic`, `unknown`
region	string	Yes	Geographic region: `northeast`, `southeast`, `midwest`, `southwest`, `west`, `pacific`
menopause_status	string	Yes	Status: `premenopause`, `perimenopause`, `postmenopause`, `unknown`
bmi	number	No	Body Mass Index (10-60)
smoker	boolean	No	Current smoker status
hypertension	boolean	No	Hypertension diagnosis
diabetes	boolean	No	Diabetes diagnosis
family_history_breast_cancer	boolean	No	Family history of breast cancer
notes	string	No	Additional clinical notes (max 500 characters)

Response (201 Created)

{
  "status": "success",
  "data": {
    "id": "pat_a1b2c3d4e5f6",
    "age_years": 52,
    "age_months": 0,
    "race": "caucasian",
    "ethnicity": "non_hispanic",
    "region": "northeast",
    "menopause_status": "perimenopause",
    "bmi": 26.5,
    "smoker": false,
    "hypertension": false,
    "diabetes": false,
    "family_history_breast_cancer": false,
    "notes": "Initial patient intake",
    "created_at": "2024-02-15T14:30:00Z",
    "updated_at": "2024-02-15T14:30:00Z"
  }
}

Response Schema

DeidentifiedPatientOutput

Field	Type	Description
id	string	Unique de-identified patient identifier (pat_*)
age_years	integer	Patient age in years
age_months	integer	Additional months
race	string	Race category
ethnicity	string	Ethnicity
region	string	Geographic region
menopause_status	string	Menopause status
bmi	number	Body Mass Index
smoker	boolean	Current smoker status
hypertension	boolean	Hypertension diagnosis
diabetes	boolean	Diabetes diagnosis
family_history_breast_cancer	boolean	Family history of breast cancer
notes	string	Clinical notes
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

Example Using cURL

curl -X POST https://api.menotime.timelessbiotech.com/v1/patients \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "age_years": 52,
    "age_months": 0,
    "race": "caucasian",
    "ethnicity": "non_hispanic",
    "region": "northeast",
    "menopause_status": "perimenopause",
    "bmi": 26.5,
    "smoker": false,
    "hypertension": false,
    "diabetes": false,
    "family_history_breast_cancer": false,
    "notes": "Initial patient intake"
  }'

Example Using Python

import requests

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

patient_data = {
    "age_years": 52,
    "race": "caucasian",
    "ethnicity": "non_hispanic",
    "region": "northeast",
    "menopause_status": "perimenopause",
    "bmi": 26.5
}

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

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

List Patients

Retrieve a paginated list of de-identified patients.

Endpoint: GET /patients

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)
menopause_status	string	None	Filter by menopause status
region	string	None	Filter by region
race	string	None	Filter by race

Response (200 OK)

{
  "status": "success",
  "data": [
    {
      "id": "pat_a1b2c3d4e5f6",
      "age_years": 52,
      "age_months": 0,
      "race": "caucasian",
      "ethnicity": "non_hispanic",
      "region": "northeast",
      "menopause_status": "perimenopause",
      "bmi": 26.5,
      "smoker": false,
      "hypertension": false,
      "diabetes": false,
      "family_history_breast_cancer": false,
      "created_at": "2024-02-15T14:30:00Z",
      "updated_at": "2024-02-15T14:30:00Z"
    },
    {
      "id": "pat_g7h8i9j0k1l2",
      "age_years": 48,
      "age_months": 6,
      "race": "african_american",
      "ethnicity": "non_hispanic",
      "region": "southeast",
      "menopause_status": "perimenopause",
      "bmi": 28.3,
      "smoker": true,
      "hypertension": true,
      "diabetes": false,
      "family_history_breast_cancer": true,
      "created_at": "2024-02-10T10:15:00Z",
      "updated_at": "2024-02-12T16:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 145,
    "pages": 8
  }
}

Example Using cURL

curl -X GET "https://api.menotime.timelessbiotech.com/v1/patients?page=1&limit=20&menopause_status=perimenopause" \
  -H "Authorization: Bearer {access_token}"

Get Patient

Retrieve a single de-identified patient by ID.

Endpoint: GET /patients/{id}

Authentication: Required (provider, readonly, admin role)

Path Parameters

Parameter	Type	Description
id	string	Patient ID (pat_*)

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": "pat_a1b2c3d4e5f6",
    "age_years": 52,
    "age_months": 0,
    "race": "caucasian",
    "ethnicity": "non_hispanic",
    "region": "northeast",
    "menopause_status": "perimenopause",
    "bmi": 26.5,
    "smoker": false,
    "hypertension": false,
    "diabetes": false,
    "family_history_breast_cancer": false,
    "notes": "Initial patient intake",
    "created_at": "2024-02-15T14:30:00Z",
    "updated_at": "2024-02-15T14:30:00Z",
    "visits": [
      {
        "id": "vis_x1y2z3a4b5c6",
        "visit_date": "2024-02-15",
        "visit_type": "initial_consultation",
        "created_at": "2024-02-15T14:30:00Z"
      }
    ]
  }
}

Example Using cURL

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

Update Patient

Update an existing patient record.

Endpoint: PUT /patients/{id}

Authentication: Required (provider, admin role)

Request

{
  "menopause_status": "postmenopause",
  "bmi": 25.8,
  "notes": "Updated after consultation"
}

Updatable Fields

Field	Type	Description
menopause_status	string	Menopause status
bmi	number	Body Mass Index
smoker	boolean	Smoker status
hypertension	boolean	Hypertension diagnosis
diabetes	boolean	Diabetes diagnosis
family_history_breast_cancer	boolean	Family history of breast cancer
notes	string	Clinical notes

Response (200 OK)

{
  "status": "success",
  "data": {
    "id": "pat_a1b2c3d4e5f6",
    "age_years": 52,
    "age_months": 0,
    "race": "caucasian",
    "ethnicity": "non_hispanic",
    "region": "northeast",
    "menopause_status": "postmenopause",
    "bmi": 25.8,
    "smoker": false,
    "hypertension": false,
    "diabetes": false,
    "family_history_breast_cancer": false,
    "notes": "Updated after consultation",
    "created_at": "2024-02-15T14:30:00Z",
    "updated_at": "2024-02-18T11:20:00Z"
  }
}

Example Using cURL

curl -X PUT https://api.menotime.timelessbiotech.com/v1/patients/pat_a1b2c3d4e5f6 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "menopause_status": "postmenopause",
    "bmi": 25.8
  }'

Batch Upload Patients

Upload multiple de-identified patient records via CSV file.

Endpoint: POST /patients/batch

Authentication: Required (provider, admin role)

Request

Multipart form data with CSV file:

POST /patients/batch HTTP/1.1
Content-Type: multipart/form-data

------boundary
Content-Disposition: form-data; name="file"; filename="patients.csv"
Content-Type: text/csv

age_years,age_months,race,ethnicity,region,menopause_status,bmi,smoker,hypertension,diabetes,family_history_breast_cancer,notes
52,0,caucasian,non_hispanic,northeast,perimenopause,26.5,false,false,false,false,"Initial patient intake"
48,6,african_american,non_hispanic,southeast,perimenopause,28.3,true,true,false,true,"Follow-up visit"
55,3,asian,non_hispanic,west,postmenopause,23.1,false,false,true,false,"Annual checkup"
------boundary--

CSV Column Requirements

Column	Required	Description
age_years	Yes	Patient age in years
age_months	No	Additional months
race	Yes	Race category
ethnicity	Yes	Ethnicity
region	Yes	Geographic region
menopause_status	Yes	Menopause status
bmi	No	Body Mass Index
smoker	No	Boolean (true/false)
hypertension	No	Boolean (true/false)
diabetes	No	Boolean (true/false)
family_history_breast_cancer	No	Boolean (true/false)
notes	No	Text notes

Response (202 Accepted)

{
  "status": "success",
  "data": {
    "batch_id": "batch_m1n2o3p4q5r6",
    "file_name": "patients.csv",
    "total_records": 3,
    "processing": true,
    "created_at": "2024-02-15T14:30:00Z"
  },
  "message": "Batch processing started. Check status with batch_id."
}

Check Batch Status

Endpoint: GET /patients/batch/{batch_id}

Response

{
  "status": "success",
  "data": {
    "batch_id": "batch_m1n2o3p4q5r6",
    "file_name": "patients.csv",
    "total_records": 3,
    "processed": 3,
    "successful": 3,
    "failed": 0,
    "processing": false,
    "completed_at": "2024-02-15T14:35:00Z",
    "errors": []
  }
}

Example Using Python

import requests

files = {'file': open('patients.csv', 'rb')}
headers = {"Authorization": f"Bearer {access_token}"}

response = requests.post(
    "https://api.menotime.timelessbiotech.com/v1/patients/batch",
    files=files,
    headers=headers
)

batch_id = response.json()["data"]["batch_id"]
print(f"Batch processing started: {batch_id}")

Data De-identification

All patient records are de-identified according to HIPAA Safe Harbor standards. The following identifiers are removed or aggregated:

Removed: Medical record numbers, account numbers, social security numbers, names, addresses, contact information, dates of birth, medical license numbers, vehicle identifiers
Aggregated: Age is collected in ranges (years + months), preventing exact date reconstruction
Controlled: Geographic location limited to 6 regions instead of specific locations

All records are assigned unique de-identified identifiers (pat_*) that have no connection to original patient identifiers.

Validation Rules

Age Validation

age_years: Must be between 18 and 120
age_months: Must be between 0 and 11

BMI Validation

Must be between 10 and 60 kg/m²
Field is optional but if provided must meet requirements

Enum Values

All enumerated fields must match exactly (case-sensitive):

race: caucasian, african_american, asian, hispanic, native_american, pacific_islander, other, unknown
ethnicity: hispanic, non_hispanic, unknown
region: northeast, southeast, midwest, southwest, west, pacific
menopause_status: premenopause, perimenopause, postmenopause, unknown

Notes Field

Maximum 500 characters
Plain text only, no HTML or special formatting

Error Examples

Invalid Age

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": [
    {
      "field": "age_years",
      "message": "Age must be between 18 and 120"
    }
  ]
}

Missing Required Field

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": [
    {
      "field": "menopause_status",
      "message": "This field is required"
    }
  ]
}

Invalid Enum Value

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": [
    {
      "field": "race",
      "message": "Invalid value 'mixed'. Valid values: caucasian, african_american, asian, hispanic, native_american, pacific_islander, other, unknown"
    }
  ]
}