API reference

Patients

Find, read, register and update patients. Search is forgiving: any word order, common spelling variants, any part of the phone number, or just the patient number.

Search or list patients

GET/api/v1/patientsScope: patients:read

With q, returns the best matches (ranked, no pages). Without q, lists all patients newest first, in pages.

Field	Where	Type	Description
`q`	after ?	string	Name (any order or spelling), any part of the phone, or patient ID. “kartik”, “7313” and “123” all work.
`limit`	after ?	integer	How many to return. Default 25, max 100.
`cursor`	after ?	string	Next page, from meta.next_cursor (lists only).

Example request

bash

curl "https://your-healthfix-site/api/v1/patients?q=ravi%20kumar&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

json

{
  "data": [
    { "id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42", "patient_code": "CHC000123", "full_name": "Ravi Kumar", "phone": "9876501234", "last_visit": "2026-09-12", "visit_count": 4, "…": "…" }
  ]
}

Get a patient

GET/api/v1/patients/{id}Scope: patients:read

One patient's profile and visit count.

Field	Where	Type	Description
`id`required	in the path	uuid	The patient's ID.

Example request

bash

curl "https://your-healthfix-site/api/v1/patients/0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

json

{
  "data": {
    "id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42",
    "patient_code": "CHC000123",
    "full_name": "Ravi Kumar",
    "gender": "male",
    "date_of_birth": "1985-06-14",
    "phone": "9876501234",
    "email": null,
    "blood_group": "B+",
    "address": "12 MG Road, Pune",
    "allergies": "Penicillin",
    "medical_history": "Type 2 diabetes since 2019",
    "last_visit": "2026-09-12",
    "visit_count": 4,
    "created_at": "2026-03-02T10:15:00Z",
    "updated_at": "2026-09-12T11:02:00Z"
  }
}

Get a patient's summary

GET/api/v1/patients/{id}/summaryScope: patients:read

Quick facts for a patient screen: allergies, plus how many consultations, documents, lab results (and abnormal ones), care plans, notes and invoices they have, and the balance due.

Field	Where	Type	Description
`id`required	in the path	uuid	The patient's ID.

Example request

bash

curl "https://your-healthfix-site/api/v1/patients/0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42/summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

Register a patient

POST/api/v1/patientsScope: patients:write

Creates a patient and assigns the next patient ID. Search first so you don't register the same person twice.

Field	Where	Type	Description
`full_name`required	JSON body	string	Patient's full name.
`gender`required	JSON body	string	male, female or other.
`phone`required	JSON body	string	Mobile number, 6 to 20 characters.
`date_of_birth`	JSON body	date	YYYY-MM-DD. Can't be in the future.
`email`	JSON body	string	Email address.
`blood_group`	JSON body	string	A+, A-, B+, B-, AB+, AB-, O+ or O-.
`address`	JSON body	string	Postal address.
`allergies`	JSON body	string	Known allergies, free text.
`medical_history`	JSON body	string	Past medical history, free text.

Example request

bash

curl -X POST "https://your-healthfix-site/api/v1/patients" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Asha Verma","gender":"female","phone":"9876543210","date_of_birth":"1992-01-20"}'

Example response

json

{
  "data": {
    "id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42",
    "patient_code": "CHC000123",
    "full_name": "Asha Verma",
    "gender": "male",
    "date_of_birth": "1985-06-14",
    "phone": "9876501234",
    "email": null,
    "blood_group": "B+",
    "address": "12 MG Road, Pune",
    "allergies": "Penicillin",
    "medical_history": "Type 2 diabetes since 2019",
    "last_visit": "2026-09-12",
    "visit_count": 4,
    "created_at": "2026-03-02T10:15:00Z",
    "updated_at": "2026-09-12T11:02:00Z"
  }
}

Returns 201 Created with the new patient.

Update a patient

PUT/api/v1/patients/{id}Scope: patients:write

Replaces the patient's details. Send every field you want to keep: read the patient first, change what you need, send it all back.

Field	Where	Type	Description
`id`required	in the path	uuid	The patient's ID.
`full_name`required	JSON body	string	Patient's full name.
`gender`required	JSON body	string	male, female or other.
`phone`required	JSON body	string	Mobile number, 6 to 20 characters.
`date_of_birth`	JSON body	date	YYYY-MM-DD. Can't be in the future.
`email`	JSON body	string	Email address.
`blood_group`	JSON body	string	A+, A-, B+, B-, AB+, AB-, O+ or O-.
`address`	JSON body	string	Postal address.
`allergies`	JSON body	string	Known allergies, free text.
`medical_history`	JSON body	string	Past medical history, free text.

Example request

bash

curl -X PUT "https://your-healthfix-site/api/v1/patients/0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Ravi Kumar","gender":"male","phone":"9876501234","date_of_birth":"1985-06-14","allergies":"Penicillin, sulfa drugs"}'

Example response

json

{
  "data": {
    "id": "0b9f6f7e-3c1a-4f7e-9b1e-5f2d8a7c1e42",
    "patient_code": "CHC000123",
    "full_name": "Ravi Kumar",
    "gender": "male",
    "date_of_birth": "1985-06-14",
    "phone": "9876501234",
    "email": null,
    "blood_group": "B+",
    "address": "12 MG Road, Pune",
    "allergies": "Penicillin",
    "medical_history": "Type 2 diabetes since 2019",
    "last_visit": "2026-09-12",
    "visit_count": 4,
    "created_at": "2026-03-02T10:15:00Z",
    "updated_at": "2026-09-12T11:02:00Z"
  }
}