Getting Started

🔑
Everything in this API is scoped to your organisation. You authenticate with your Provider ID paired with an API key — both live on the vendor portal's Integrations page.

The Precursor API gives your practice-management or booking system the same capabilities as the vendor portal: manage bookings, view patients and leave clinical notes, upload and download documents, publish availability, keep location contacts current, administer portal users, and read your organisation's activity feed.

API Reference

Every endpoint, with request and response examples

Vendor portal

Create and revoke your API keys

Talk to us

We're happy to help you integrate

1. Get your credentials

Provider ID — your organisation's identifier. Not a secret, but a key only works together with it.
API keys — create one per system that talks to Precursor, so each can be revoked on its own (format prec_ followed by 64 hex characters).

Send both on every request:

X-Precursor-Provider-Id: 3f2b8c1a-9d4e-4a7b-8c6f-2e1d5a9b7c3e
X-Precursor-Api-Key: prec_4f8a2c...

⚠️
Treat API keys like admin passwords. A key can do everything your organisation's portal admins can do, across all of your locations. Revoking a key takes effect within five minutes.

2. Make your first call

GET /organisation returns your own organisation record — it's the quickest way to confirm your credentials work:

curl "https://api.precursor.com.au/api/v1/organisation" \
  -H "X-Precursor-Provider-Id: YOUR_PROVIDER_ID" \
  -H "X-Precursor-Api-Key: YOUR_API_KEY"

{
  "providerId": "3f2b8c1a-9d4e-4a7b-8c6f-2e1d5a9b7c3e",
  "businessName": "Example Radiology Pty Ltd",
  "abnAcn": "12 345 678 901",
  "email": "[email protected]",
  "phone": "+61 7 5555 0100",
  "headOffice": { "address": "1 Example St", "city": "Brisbane", "state": "QLD", "postalCode": "4000" },
  "createdAt": "2026-07-06T02:20:59.000+00:00",
  "updatedAt": "2026-08-22T10:43:46.000+00:00"
}

A 401 {"message": "Unauthorized"} means a header is missing; a 403 {"message": "Forbidden"} means the provider ID / key pair isn't valid.

3. Explore the API

All endpoints live under https://api.precursor.com.au/api/v1/ — the API Reference documents each one with examples.

Area	What you can do
Bookings	List your bookings; confirm a requested time; propose a reschedule; move a booking the patient has already agreed to
Patients	Your patient roster and profiles; clinical notes against your services; document upload and download
Availability	Read and update per-service booking settings — delivery mode, self-service windows, duration, lead time
Locations	Your locations and organisation record, with contact email/phone editable
Users	Add, update and remove portal users, including roles and location access
Activity	Your organisation's audit feed — every portal and API action

Concepts worth knowing

Booking lifecycle. A patient requests a window; you confirm a concrete time or propose a different one, which the patient accepts in their app. Moving a booking without the patient accepting in-app requires you to attest they agreed (memberAgreed: true). There is no cancel operation.

Times are local clinic time. Appointment times and booking windows are wall-clock strings with no timezone offset — yyyy-MM-ddTHH:mm and HH:mm. Record timestamps (createdAt, updatedAt) are UTC ISO-8601. Don't convert between them.

Documents move in three steps. Initiate the upload (you get a presigned URL), HTTP PUT the raw bytes to it with exactly the returned Content-Type, then call complete — Precursor validates the content and files the document, or deletes anything that fails validation. Up to 100 MB: DICOM, PDF, images, macro-free Office documents and text formats. Downloads return a short-lived presigned URL.

Pagination. List endpoints take limit and an opaque cursor, and return nextCursor (null when you've reached the end).

Errors. Non-2xx responses use a stable envelope: {"error": {"code": "...", "message": "..."}}. A 409 conflict means the record changed while your request ran — retry it.

Privacy by design. You only ever see your own organisation's data: your bookings, your notes, your activity. Patient document access is recorded in your activity feed — the same standard the portal holds itself to.

Need a hand?

Email [email protected] — tell us what system you're connecting and we'll point you at the right endpoints.