Docs / Integrators

rxConnect® electronic prescribing API documentation

Integrate eRx electronic prescribing and the Services Australia Healthcare Identifiers Service into your own PMS, telehealth, clinical or healthcare application.

Before you beginHITORI provides environment-specific base URLs, rxConnect® OAuth credentials and hiConnect® JWT configuration. A Postman collection and further detailed documentation are also provided when the middleware is provisioned in your cloud environment. Keep all credentials in server-side environment variables.

Environments

Staging and production are separated for both services. Use the exact domains supplied for your organisation.

ServiceStaging patternProduction pattern
rxConnect®https://rxconnect-stg.<domain>.com.auhttps://rxconnect.<domain>.com.au
hiConnect®https://hi-stg.<domain>.com.auhttps://hi.<domain>.com.au

rxConnect® quickstart

1. Obtain an OAuth token

Use the confidential client credentials supplied for the target environment.

Request
curl -X POST "https://rxconnect-stg.<domain>.com.au/o/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$RXCONNECT_CLIENT_ID" \
  -d "client_secret=$RXCONNECT_CLIENT_SECRET"

When generating a token for the patient React/iFrame view, also include the patient’s unique PMS identifier as patient_guid. The returned token is passed to the component as the t query parameter.

2. Create a paper prescription or eScript

POST a JSON object containing PayloadType, Patient, Clinician and PrescribedItem. rxConnect® generates the SCID, selects the matching paper or electronic eRx format, and forwards the correctly formatted request to eRx.

Request
curl -X POST "https://rxconnect-stg.<domain>.com.au/eprescriptions/erx001/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data @prescription.json

Authentication

rxConnect® endpoints use OAuth 2.0 bearer tokens. Read operations require the read scope; create and lifecycle operations require read and write. hiConnect® uses a separate JWT bearer token for each environment. Integration testing may use a provided long-lived token; production systems should generate short-lived server-side tokens, typically valid for 5–15 minutes.

Create-prescription payload

The erx001 request must be populated from your local patient, clinician and medication records.

ObjectRepresentative fields
PatientUnique ID and patient number, legal and Medicare names, address, contact details, Medicare details, date of birth, sex and PatientIHI retrieved through hiConnect®.
ClinicianPrescriber and provider numbers, name, practice details, prescribing system, HPI-O and HPI-I.
PrescribedItemMedication identifiers and names, PBS code, quantity, repeats, instructions, script number and controlled-substance reference where applicable.

Paper prescription or eScript

Set the top-level PayloadType field on each create request to choose the prescription format. rxConnect® validates the request against the matching eRx schema and stores the selected type with the prescription.

PayloadTypeeRx formatBehaviour
paperETP1Creates a paper prescription. Electronic token metadata and ETP identifiers are omitted. The generated paper-script PDF is available from /eprescriptions/{scid}/paperscript/.
eScriptETP2Creates an electronic prescription. Electronic token metadata can be supplied for SMS or email delivery, and electronic-only lifecycle operations are available.
Create-request selector
{
  "PayloadType": "eScript",
  "Patient": { … },
  "Clinician": { … },
  "PrescribedItem": { … }
}
Backwards compatibilityIf PayloadType is omitted, rxConnect® uses the configured default for that deployment. New integrations should send the field explicitly. Values other than paper or eScript return 400.

Token delivery, annotations and tags

eScript payloads can include optional token-delivery metadata, prescriber annotations and item tags. rxConnect® validates and maps these schema-shaped JSON objects into the eRx request.

TokenMetadata

Place TokenMetadata inside PrescribedItem and supply exactly one electronic address. The address Type must be sms or email, and Value is required.

SMS token delivery
{
  "PrescribedItem": {
    "TokenMetadata": {
      "ElectronicAddresses": {
        "ElectronicAddress": [
          { "Type": "sms", "Value": "0412345678" }
        ]
      }
    }
  }
}

If TokenMetadata is omitted for an eScript, rxConnect® uses PatientMobileNumber for SMS when available, otherwise PatientEmail. Token metadata is omitted for paper prescriptions and emergency-supply prescriptions.

Prescriber annotations

Add Annotations inside PrescribedItem. Annotation may be one object or a list. Each entry requires an integer SupplyNumber and a non-empty Value; multiple entries must use the same supply number and are combined into the eRx annotation value.

Prescription annotation
{
  "PrescribedItem": {
    "Annotations": {
      "Annotation": {
        "SupplyNumber": 0,
        "Value": "for dental treatment only"
      }
    }
  }
}

Item tags

Add the top-level Tags object as a sibling of Patient, Clinician and PrescribedItem. Tag may be one object or a list, and every tag requires a non-empty Key and Value.

MySL consent and pharmacy handling
{
  "Tags": {
    "Tag": [
      { "Key": "MySLConsent", "Value": "Y" },
      { "Key": "SendToPharmacy", "Value": "DosingPoint" }
    ]
  }
}

Supported SendToPharmacy values include DosingPoint, StagedSupply and RepeatOnFile. Use tags only when they apply to the prescribing workflow and relevant conformance requirements.

Optional React and iFrame integration

HITORI supplies a customisable React component for the patient eScript list and post-create actions. Using it is optional: you can embed it directly, wrap it in an iFrame, adapt and style it to your own interface, or omit it entirely and build a fully custom UI against the rxConnect® API.

If you use the supplied component, pass the OAuth access token as t. The token is linked to the patient_guid used during authentication so the component filters prescriptions for that patient.

Optional iFrame example
<iframe
  src="https://<react-app-domain>/?t=<access_token>"
  width="100%"
  height="600"
  style="border:0"
></iframe>
Choose the approach that fits your productUse the supplied component for a faster implementation, customise its presentation, or retain complete control with your own interface and workflows.

ePrescription workflows

The initial create action is sent from your application. The supplied React component handles cancellation, amendment, cessation and token re-issue for prescriptions in the patient list.

CodeActionMethod
erx001Create and store a prescriptionPOST
erx003Retrieve for dispensingGET
erx023Cancel an itemPOST
erx025Retrieve for amendmentGET
erx027Amend a prescriptionPOST
erx049Request for viewGET
erx061Cease an electronic prescriptionPOST
erx065Re-issue an electronic tokenPOST

eRx ASPR service-provider registration

Register a prescribing service provider through rxConnect® using the OAuth-protected POST /serviceproviders/ endpoint. rxConnect® validates the provider's PKCS#12 credential, submits the registration to the eRx ASPR service using mutual TLS, and securely stores the returned eRx entity ID and certificate metadata in your provisioned environment.

POST/serviceproviders/

Send the request as multipart/form-data. The certificate must be a valid, unexpired .p12 bundle containing its private key and issued by an eRx-authorised certificate authority.

GroupFields
Providername, prescriber_number, optional ahpra_number
Contact and addresscontact_name, contact_email, contact_phone, optional contact_fax, address_line_1, city, state, country, postcode
Credentialcertificate, certificate_password
User agreementuser_agreement_accepted, user_agreement_version, user_agreement_accepted_at, user_agreement_accepted_by_name, optional user_agreement_accepted_by_user_id
Register a service provider
curl -X POST "https://rxconnect-stg.<domain>.com.au/serviceproviders/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "name=Example Medical Clinic" \
  -F "prescriber_number=1234567A" \
  -F "contact_name=Dr Example" \
  -F "contact_email=doctor@example.com" \
  -F "contact_phone=0399999999" \
  -F "address_line_1=1 Example Street" \
  -F "city=Melbourne" \
  -F "state=VIC" \
  -F "country=Australia" \
  -F "postcode=3000" \
  -F "certificate=@service-provider.p12" \
  -F "certificate_password=$CERTIFICATE_PASSWORD" \
  -F "user_agreement_accepted=true" \
  -F "user_agreement_version=<version>" \
  -F "user_agreement_accepted_at=2026-11-02T10:00:00+11:00" \
  -F "user_agreement_accepted_by_name=Dr Example"
201 response
{
  "status": "success",
  "entity_id": "<eRx entity ID>",
  "service_provider_id": 123
}

Validation failures return 400. Invalid or incomplete eRx ASPR responses return 502; connectivity or upstream service failures return the applicable upstream status, or 503 when no upstream response is available.

rxConnect® API reference

POST/o/token/
POST/eprescriptions/erx001/
GET/eprescriptions/{scid}/erx003/
POST/eprescriptions/{scid}/erx023/
GET/eprescriptions/{scid}/erx025/
POST/eprescriptions/{scid}/erx027/
GET/eprescriptions/{scid}/erx049/
POST/eprescriptions/{scid}/erx061/
POST/eprescriptions/{scid}/erx065/
GET/eprescriptionlists?t={patient_token}
GET/eprescriptions/{scid}/paperscript/
POST/serviceproviders/
GET/health/

HI Service

The included HI Service integration is called hiConnect®. It provides the Services Australia connection used to retrieve or verify a patient’s Individual Healthcare Identifier. Store the returned ihiNumber in your system, then populate PatientIHI in the rxConnect® create-prescription payload.

POST/api/IHI

Swagger documentation is available in each deployed environment at /index.html.

IHI lookup requests

Send demographics with one supported search identifier. Medicare lookup uses medicareCardNumber and medicareIRN. You may alternatively verify an existing ihiNumber, or search with a DVA file number, mobile number or email where supported.

Medicare lookup
curl -X POST "https://hi-stg.<domain>.com.au/api/IHI" \
  -H "Authorization: Bearer $HICONNECT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "medicareCardNumber": "<10-digit number>",
    "medicareIRN": "<IRN>",
    "dateOfBirth": "YYYY-MM-DD",
    "givenName": "<given name>",
    "familyName": "<family name>",
    "sex": "<M|F|I|N>"
  }'

If this information is not already captured in compliant client-side audit logs, include hpii, hpio and LocalUserId in every request. Validate IHI values using the Luhn algorithm and validate Medicare card numbers before calling the service.

Recommended timingCall hiConnect® during patient registration and use a scheduled reconciliation so the IHI is available before creating an eScript.

Responses and edge cases

A successful response includes ihiNumber, ihiStatus and recordStatus. Handle these documented HI Service outcomes explicitly:

Error codeMeaningIntegrator action
01611Duplicate IHI resolved to another IHI.Re-verify the returned resolvedIHI before saving it.
01614Retired IHI.Do not use the identifier; correct the patient identity record.
01613Expired IHI.Do not use the identifier; repeat identification with current details.
01439No IHI record found.Review patient demographic and identifier data.

Errors

rxConnect® commonly returns 400 for invalid or missing input, 401 for missing or invalid authentication, 404 when the prescription or operation cannot be found, and 500 for unexpected processing errors. Do not automatically retry validation or identity errors without correcting the request.

Security and deployment

  • Store base URLs, OAuth client credentials and JWT material in server-side environment variables.
  • Use HTTPS for every application and endpoint.
  • Use separate credentials for staging and production.
  • Provide HITORI with the staging and production origins that must be allowed by CORS.
  • Keep patient payloads and bearer tokens out of logs, browser bundles and support messages.

Contact HITORI

When requesting support, include the environment, timestamp, operation or endpoint, and SCID or HI Service error code where relevant. Do not include access tokens or unnecessary patient information.