Developers
Open ManaNotes
On this page
Patients

Patients API

Create, retrieve, update, list and archive the patients in your clinic.

The patient object
idstring
Unique identifier (ObjectId).
PractitionerIdstring
The practitioner/clinic the patient belongs to.
FirstNamestring
Patient’s given name.
LastNamestring
Patient’s family name.
UTCDateOfBirthstring | null
Date of birth — UTC midnight of the day, ISO 8601.
NHIstring | null
NZ National Health Index number, e.g. ABC1234.
Genderstring | null
Patient gender.
Emailstring | null
Primary email for reminders.
Mobilestring | null
Mobile number, e.g. +6421….
Addressobject | null
Structured address (Line1, Suburb, City, PostCode, Country, …).
Employerobject | null
Employer (EmployerName, Address).
HomeLocationIdstring | null
The patient’s home site (see locations). null on patients from before the clinic adopted locations: treat it as the default site.
IsDeletedboolean
Whether the patient is archived.
createdAtstring
ISO 8601 creation timestamp.
updatedAtstring
ISO 8601 last-update timestamp.
POST/api/v1/patients

Create a patient

Adds a new patient to your clinic. FirstName and LastName are required; everything else is optional. Unknown fields are rejected with 400. Requires patients:write.

Body parameters
FirstNamestringrequired
Given name.
LastNamestringrequired
Family name.
UTCDateOfBirthstringoptional
Date of birth, ISO 8601 — send UTC midnight of the day (1991-04-22T00:00:00Z).
NHIstringoptional
NZ NHI number.
Emailstringoptional
Primary email address.
Mobilestringoptional
Mobile number.
Genderstringoptional
Patient gender.
Addressobjectoptional
Structured address object.
HomeLocationIdstringoptional
The patient’s home site (see locations). Omitted: the practitioner’s home site, else the clinic’s default.
Request
cURL
curl https://api.mananotes.co.nz/api/v1/patients \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "FirstName": "Aroha",
    "LastName": "Ngata",
    "UTCDateOfBirth": "1991-04-22T00:00:00Z",
    "NHI": "ABC1234",
    "Mobile": "+64211234567"
  }'
Response
200 OK · application/json
{
  "data": {
    "id": "65f0c2a1b3d4e5f6a7b8c9d0",
    "FirstName": "Aroha",
    "LastName": "Ngata",
    "UTCDateOfBirth": "1991-04-22T00:00:00Z",
    "NHI": "ABC1234",
    "Mobile": "+64211234567",
    "IsDeleted": false,
    "createdAt": "2026-06-20T03:11:55Z",
    "updatedAt": "2026-06-20T03:11:55Z"
  }
}
GET/api/v1/patients

List patients

Returns a paginated list of patients in your clinic. Requires patients:read.

Query parameters
limitintegeroptional
1–200. Defaults to 20.
offsetintegeroptional
Number of records to skip.
searchstringoptional
Filter by name, email, mobile or NHI.
locationIdsstring[]optional
Only patients whose home site is one of these (see locations). Repeat the parameter or comma-separate the ids. The default site also matches patients with no home site. Also narrows search. Omitted: all sites.
Request
cURL
curl "https://api.mananotes.co.nz/api/v1/patients?limit=2&search=ngata" \
  -H "Authorization: Bearer eyJhbGci..."
Response
200 OK · application/json
{
  "data": [
    {
      "id": "65f0c2a1b3d4e5f6a7b8c9d0",
      "FirstName": "Aroha",
      "LastName": "Ngata",
      "NHI": "ABC1234"
    }
  ],
  "totalCount": 1,
  "limit": 2,
  "offset": 0
}
GET/api/v1/patients/{id}

Retrieve a patient

Fetches a single patient by id. Requires patients:read.

Path parameters
idstringrequired
The id of the patient.
Request
cURL
curl https://api.mananotes.co.nz/api/v1/patients/65f0c2a1b3d4e5f6a7b8c9d0 \
  -H "Authorization: Bearer eyJhbGci..."
Response
200 OK · application/json
{
  "data": {
    "id": "65f0c2a1b3d4e5f6a7b8c9d0",
    "FirstName": "Aroha",
    "LastName": "Ngata",
    "Email": "aroha@example.co.nz",
    "Mobile": "+64211234567",
    "NHI": "ABC1234",
    "IsDeleted": false
  }
}
PATCH/api/v1/patients/{id}

Update a patient

Updates the supplied fields on a patient. Omitted fields are left unchanged. Requires patients:write.

Path parameters
idstringrequired
The id of the patient.
Body parameters
Emailstringoptional
New primary email.
Mobilestringoptional
New mobile number.
Addressobjectoptional
Replacement address object.
NHIstringoptional
Update or add the NHI number.
HomeLocationIdstringoptional
Move the patient to another home site. Omitted: unchanged.
Request
cURL
curl https://api.mananotes.co.nz/api/v1/patients/65f0c2a1b3d4e5f6a7b8c9d0 \
  -X PATCH \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{ "Email": "aroha.ngata@example.co.nz" }'
Response
200 OK · application/json
{
  "data": {
    "id": "65f0c2a1b3d4e5f6a7b8c9d0",
    "Email": "aroha.ngata@example.co.nz",
    "updatedAt": "2026-06-20T04:02:10Z"
  }
}
DELETE/api/v1/patients/{id}

Archive a patient

Soft-deletes a patient — flagged as deleted (cascading as in the app), never destroyed, preserving history for ACC and audit. Requires patients:write.

Path parameters
idstringrequired
The id of the patient to archive.
Request
cURL
curl https://api.mananotes.co.nz/api/v1/patients/65f0c2a1b3d4e5f6a7b8c9d0 \
  -X DELETE \
  -H "Authorization: Bearer eyJhbGci..."
Response
200 OK · application/json
{
  "data": {
    "id": "65f0c2a1b3d4e5f6a7b8c9d0",
    "IsDeleted": true
  }
}