Appointments

Appointments API

Retrieve, list, book, update and cancel appointments — with ACC and inline patient/injury support.

The appointment object

idstring

Unique identifier (ObjectId).

PractitionerIdstring

The practitioner seeing the patient.

PatientIdstring | null

The patient this appointment is for.

PatientNamestring | null

Denormalised patient name.

InjuryIdstring | null

The injury (and its ACC45 claim) being treated.

BillableItemIdstring

The billable item (service) booked.

LocationIdstring | null

The site the appointment is at (see locations). null on appointments from before the clinic adopted locations: treat it as the default site.

Typeenum | null

Deprecated. No longer written — null on every new appointment; legacy rows may still carry ACC_INITIAL, ACC_FOLLOWUP, SELF_FUND_INITIAL, SELF_FUND_FOLLOWUP or OTHER. Use BillableItemId and InjuryId instead.

Statusstring

Appointment status.

UTCStartTimestring

ISO 8601 start time (UTC).

UTCEndTimestring

ISO 8601 end time (UTC).

Notesstring | null

Free-text booking note (not the clinical note).

createdAtstring

ISO 8601 creation timestamp.

updatedAtstring

ISO 8601 last-update timestamp.

GET/api/v1/appointments

List appointments

Returns appointments whose time falls within a date range. Requires appointments:read.

Query parameters

fromstringrequired

ISO 8601 lower bound. With Z or an offset it is that instant; without one it is clinic-local (Pacific/Auckland) time; a bare yyyy-MM-dd starts at the beginning of that clinic day.

tostringrequired

ISO 8601 upper bound, read the same way; a bare yyyy-MM-dd runs to the end of that clinic day.

locationIdsstring[]optional

Only appointments at these sites (see locations). Repeat the parameter or comma-separate the ids. The default site also matches appointments with no location. Omitted: all sites.

locationIdstringoptional

One site. Shorthand for a one-item locationIds; if you send both, the API uses all the ids given.

Request

cURL

curl "https://api.mananotes.co.nz/api/v1/appointments?from=2026-06-20&to=2026-06-20" \
  -H "Authorization: Bearer eyJhbGci..."

Response

200 OK · application/json

{
  "data": [
    {
      "id": "65f0d3b2c4e5f6a7b8c9d0e1",
      "PatientId": "65f0c2a1b3d4e5f6a7b8c9d0",
      "BillableItemId": "65f0b1...",
      "LocationId": "65f0f1...",
      "Status": "BOOKED",
      "UTCStartTime": "2026-06-20T01:30:00Z",
      "UTCEndTime": "2026-06-20T02:00:00Z"
    }
  ]
}

POST/api/v1/appointments

Book an appointment

Books an appointment. BillableItemId, UTCStartTime and UTCEndTime are required. Link an existing patient/injury by id, or create them inline with the Patient / Injury objects. Requires appointments:write.

Body parameters

BillableItemIdstringrequired

The service being booked (see Reference data).

UTCStartTimestringrequired

ISO 8601 start time.

UTCEndTimestringrequired

ISO 8601 end time.

Typeenumdeprecated

Ignored. Still accepted so existing integrations keep working, but never stored.

PatientIdstringoptional

Existing patient to book.

InjuryIdstringoptional

Existing injury / ACC claim to treat.

PractitionerIdstringoptional

Override the acting practitioner.

LocationIdstringoptional

The site to book at (see locations). Must be an active site. Omitted: the practitioner’s home site, else the clinic’s default.

Notesstringoptional

Booking note.

Patientobjectoptional

Create the patient inline (same fields as create-patient).

Injuryobjectoptional

Create the injury inline (ACCNumber, InjuryUTCDate, ReadCodes).

Request

cURL

curl https://api.mananotes.co.nz/api/v1/appointments \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "PatientId": "65f0c2a1b3d4e5f6a7b8c9d0",
    "InjuryId": "65f0e4...",
    "BillableItemId": "65f0b1...",
    "UTCStartTime": "2026-06-20T01:30:00Z",
    "UTCEndTime": "2026-06-20T02:00:00Z"
  }'

Response

200 OK · application/json

{
  "data": {
    "id": "65f0d3b2c4e5f6a7b8c9d0e1",
    "PatientId": "65f0c2a1b3d4e5f6a7b8c9d0",
    "InjuryId": "65f0e4...",
    "BillableItemId": "65f0b1...",
    "Status": "BOOKED",
    "UTCStartTime": "2026-06-20T01:30:00Z",
    "UTCEndTime": "2026-06-20T02:00:00Z",
    "createdAt": "2026-06-20T05:40:02Z"
  }
}

GET/api/v1/appointments/{id}

Retrieve an appointment

Fetches a single appointment by id. Requires appointments:read.

Path parameters

idstringrequired

The id of the appointment.

Request

cURL

curl https://api.mananotes.co.nz/api/v1/appointments/65f0d3b2c4e5f6a7b8c9d0e1 \
  -H "Authorization: Bearer eyJhbGci..."

Response

200 OK · application/json

{
  "data": {
    "id": "65f0d3b2c4e5f6a7b8c9d0e1",
    "PatientId": "65f0c2a1b3d4e5f6a7b8c9d0",
    "Status": "BOOKED",
    "UTCStartTime": "2026-06-20T01:30:00Z",
    "UTCEndTime": "2026-06-20T02:00:00Z"
  }
}

PATCH/api/v1/appointments/{id}

Update an appointment

Updates an appointment — e.g. reschedule by changing UTCStartTime/UTCEndTime, or update Notes. Omitted fields are unchanged. Requires appointments:write.

Path parameters

idstringrequired

The id of the appointment.

Body parameters

UTCStartTimestringoptional

New ISO 8601 start time.

UTCEndTimestringoptional

New ISO 8601 end time.

Notesstringoptional

Update the booking note.

BillableItemIdstringoptional

Change the booked service.

LocationIdstringoptional

Move the appointment to another site. Must be an active site, unless it is the appointment’s current one.

Request

cURL

curl https://api.mananotes.co.nz/api/v1/appointments/65f0d3b2c4e5f6a7b8c9d0e1 \
  -X PATCH \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "UTCStartTime": "2026-06-20T03:00:00Z",
    "UTCEndTime": "2026-06-20T03:30:00Z"
  }'

Response

200 OK · application/json

{
  "data": {
    "id": "65f0d3b2c4e5f6a7b8c9d0e1",
    "UTCStartTime": "2026-06-20T03:00:00Z",
    "UTCEndTime": "2026-06-20T03:30:00Z",
    "updatedAt": "2026-06-20T06:15:30Z"
  }
}

DELETE/api/v1/appointments/{id}

Cancel an appointment

Soft-deletes (cancels) an appointment. Pass deleteAssociatedTreatment=true to also remove the linked treatment. Requires appointments:write.

Path parameters

idstringrequired

The id of the appointment.

Query parameters

deleteAssociatedTreatmentbooleanoptional

Also soft-delete the linked treatment. Defaults to false.

Request

cURL

curl "https://api.mananotes.co.nz/api/v1/appointments/65f0d3b2c4e5f6a7b8c9d0e1?deleteAssociatedTreatment=true" \
  -X DELETE \
  -H "Authorization: Bearer eyJhbGci..."

Response

200 OK · application/json

{
  "data": {
    "id": "65f0d3b2c4e5f6a7b8c9d0e1",
    "IsDeleted": true
  }
}