Patients

Get a single patient

Retrieves a patient's basic information and health profile.

GET /patients/:patientId

URL Parameters

Parameter	Description
`patientId`	The patient's record ID

curl "https://partner-staging.i-screen.com.au/v1/patients/610ad2a60ae7ef00115c0aa3" \
  -H "Authorization: Bearer f3ee05b1e3d140a3b17456fb69d28cd9-5f6a46513aa48d0bf80a04c7d52c9805633070a7803d3bd4"

Response

{
  "_id": "610ad2a60ae7ef00115c0aa3",
  "profile": {
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "0412 345 678",
    "gender": "F",
    "dob": "31/12/2000",
    "address": {
      "line1": "7 Example St",
      "city": "Brisbane City",
      "state": "QLD",
      "country": "Australia",
      "zip": "4006"
    }
  },
  "allowIscreenPathologyFormNotification": true,
  "allowIscreenResultsNotification": true,
  "status": "active",
  "email": "jane.doe@example.com",
  "umrn": "90020709",
  "createdAt": "2021-08-04T17:47:18.840Z",
  "updatedAt": "2021-08-04T17:47:18.840Z"
}

Get multiple patients

Retrieves multiple patients under the current practitioner.

GET /patients

Query Parameters

Parameter	Required	Default	Description
`skip`	No	0	Number of records to skip
`limit`	No	10	Max records to retrieve (max: 100)
`umrn`	No	-	Filter by UMRN
`email`	No	-	Filter by patient email (URL-encoded)

curl "https://partner-staging.i-screen.com.au/v1/patients?skip=0&limit=10" \
  -H "Authorization: Bearer f3ee05b1e3d140a3b17456fb69d28cd9-5f6a46513aa48d0bf80a04c7d52c9805633070a7803d3bd4"

Response

{
  "total": 7,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "_id": "5ee084aa24f8a70010e682a2",
      "email": "jane.doe@example.com",
      "umrn": "90010653",
      "updatedAt": "2020-06-10T06:58:50.263Z",
      "createdAt": "2020-06-10T06:58:50.263Z",
      "status": "active",
      "profile": {
        "firstName": "Jane",
        "lastName": "Doe",
        "gender": "F",
        "phone": "0412345678",
        "dob": "13/06/1990"
      }
    }
  ]
}

Create a new patient

Creates a new patient under the current practitioner.

POST /patients

Payload

Parameter	Required	Description
`email` string	Yes	The patient's email
`allowIscreenPathologyFormNotification` boolean	No	If `true`, i-screen sends the patient a request-form/instructions email when a test from a directly purchased order is confirmed. Set to `false` if the partner handles all patient communications for this flow. This does not affect the invoice payment-link email, which is always sent.
`allowIscreenResultsNotification` boolean	No	If `true`, i-screen sends a notification email when results are available. If `false`, results won't appear on the patient dashboard until explicitly released from the practitioner portal.
`profile.firstName` string	No	First name
`profile.lastName` string	Yes	Last name
`profile.phone` string	Yes	Phone number. Must start with `0`.
`profile.gender` string	Yes	Gender. Values: `M`, `F`, `U`
`profile.dob` string	Yes	Date of birth in `dd/MM/yyyy` format. Patient must be 18 or older.
`profile.address.line1` string	Yes	Address line 1
`profile.address.line2` string	No	Address line 2
`profile.address.city` string	Yes	City
`profile.address.state` string	Yes	State
`profile.address.country` string	Yes	Country
`profile.address.zip` string	Yes	Postcode
`healthProfile.basicInfo.height` number	No	Height in cm
`healthProfile.basicInfo.weight` number	No	Weight in kg
`healthProfile.lifeStyle.isSmoker` string	No	Values: `yes`, `no`
`healthProfile.lifeStyle.alcoholUnits` string	No	Weekly alcohol units
`healthProfile.lifeStyle.diet` string	No	Values: `healthy`, `unhealthy`, `moderate`
`healthProfile.lifeStyle.exerciseFrequency` string	No	Exercise frequency
`healthProfile.lifeStyle.exerciseDuration` string	No	Exercise duration
`healthProfile.medicalHistory.lastBPCheck` date	No	Date in `dd/MM/yyyy` format
`healthProfile.medicalHistory.lastBP` string	No	Last blood pressure reading
`healthProfile.medicalHistory.pastMedicalHistory` string	No	Past medical history
`healthProfile.medicalHistory.familyMedicalCond` string	No	Family medical conditions
`healthProfile.medicalHistory.medication` string	No	Current medications
`healthProfile.medicalHistory.allergy` string	No	Known allergies
`healthProfile.medicalHistory.healthConcern` string	No	Health concerns
`healthProfile.womensHealth.menstrualStatus` string	No	Values: `premenopause`, `perimenopause`, `postmenopause`
`healthProfile.womensHealth.ageOfFirstPeriod` string	No	Age of first period
`healthProfile.womensHealth.ageOfLastPeriod` string	No	Age of last period
`healthProfile.womensHealth.isPeriodRegular` string	No	Values: `yes`, `no`
`healthProfile.womensHealth.menstrualDuration` string	No	Menstrual duration
`healthProfile.womensHealth.ovulationDuration` string	No	Ovulation duration
`healthProfile.womensHealth.hasHadMiscarriage` string	No	Values: `yes`, `no`
`healthProfile.womensHealth.pcoSyndrome` string	No	Values: `yes`, `no`, `unsure`
`healthProfile.womensHealth.moreInfo` string	No	Additional women's health info
`healthProfile.familyPlanning.inPreOrPostPregnancy` string	No	Values: `yes`, `no`, `recentlyConceived`
`healthProfile.familyPlanning.conceiveAttemptDuration` string	No	Duration of conception attempts
`healthProfile.familyPlanning.hasHadFertilityTest` string	No	Values: `yes`, `no`
`healthProfile.familyPlanning.moreInfo` string	No	Additional family planning info
`healthProfile.howDidYouHearAboutUs` string	No	How the patient heard about i-screen

curl -X POST https://partner-staging.i-screen.com.au/v1/patients \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer f3ee05b1e3d140a3b17456fb69d28cd9-5f6a46513aa48d0bf80a04c7d52c9805633070a7803d3bd4"

Payload

{
  "email": "jenny.doe@gmail.com",
  "allowIscreenPathologyFormNotification": false,
  "allowIscreenResultsNotification": false,
  "profile": {
    "firstName": "Jenny",
    "lastName": "Doe",
    "phone": "0412123123",
    "gender": "F",
    "dob": "02/12/2000",
    "address": {
      "line1": "1/2 Lang Street",
      "city": "Brunswick",
      "state": "VIC",
      "country": "Australia",
      "zip": "3000"
    }
  },
  "healthProfile": {
    "basicInfo": {
      "height": 170,
      "weight": 75.5
    },
    "lifeStyle": {
      "isSmoker": "no",
      "alcoholUnits": "2",
      "diet": "healthy",
      "exerciseFrequency": "3x per week",
      "exerciseDuration": "45 mins"
    }
  }
}

Response

{
  "_id": "610ad2a60ae7ef00115c0aa3",
  "email": "jenny.doe@gmail.com",
  "umrn": "90020710",
  "status": "active",
  "profile": {
    "firstName": "Jenny",
    "lastName": "Doe",
    "phone": "0412123123",
    "gender": "F",
    "dob": "02/12/2000",
    "address": {
      "line1": "1/2 Lang Street",
      "city": "Brunswick",
      "state": "VIC",
      "country": "Australia",
      "zip": "3000"
    }
  },
  "createdAt": "2021-08-04T17:47:18.840Z",
  "updatedAt": "2021-08-04T17:47:18.840Z"
}

Existing account

Email is the unique identifier for an i-screen account. If the email already belongs to an account, this endpoint does not create a duplicate. Instead it returns a 409 Conflict:

`reason`	Meaning
`PATIENT_ALREADY_LINKED`	The account already exists and is already linked to your practitioner. The response includes `patientId`, so you can use the existing patient.
`PATIENT_EXISTS_CONSENT_REQUIRED`	The account exists but belongs to a different practitioner, or has never been linked to one. `patientId` is withheld until the patient consents to the connection.

For PATIENT_EXISTS_CONSENT_REQUIRED, see Requesting a connection to an existing account below.

{
  "name": "Conflict",
  "message": "An i-screen account already exists for this email address...",
  "code": 409,
  "data": {
    "reason": "PATIENT_EXISTS_CONSENT_REQUIRED"
  }
}

Requesting a connection to an existing account

If a patient already has an i-screen account (PATIENT_EXISTS_CONSENT_REQUIRED above), you cannot create or patch that patient directly. Instead, request the patient's consent to connect their existing account to your practitioner.

POST /patients/link-requests

Payload

Parameter	Required	Description
`email` string	Yes	The existing patient's email

If no account exists

This endpoint is only for connecting to an account that already exists. If no i-screen account is registered under the given email at all, it returns a 404 Not Found:

{
  "name": "NotFound",
  "message": "No i-screen account exists for this email address.",
  "code": 404,
  "className": "not-found",
  "errors": {}
}

If you're not sure whether an account exists, Create a new patient first: it creates the account when there isn't one, or tells you a link request is needed (PATIENT_EXISTS_CONSENT_REQUIRED) when there is.

curl -X POST https://partner-staging.i-screen.com.au/v1/patients/link-requests \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer f3ee05b1e3d140a3b17456fb69d28cd9-5f6a46513aa48d0bf80a04c7d52c9805633070a7803d3bd4" \
  -d '{ "email": "patient@example.com" }'

Response

{
  "id": "610ad2a60ae7ef00115c0aa3",
  "patientId": null,
  "status": "pending",
  "createdAt": "2026-08-01T02:00:00.000Z",
  "expiresAt": "2026-08-08T02:00:00.000Z",
  "approvedAt": null
}

This sends i-screen's standard connection-request email directly to the patient. We email the patient, not you, since it is their consent to give. The request expires after 7 days if the patient does not respond; you may send a new request once it expires. Only one active request per patient is allowed at a time.

patientId is withheld until the patient approves. Poll or check the request to find out when they have:

GET /patients/link-requests/:linkRequestId

URL Parameters (link request)

Returns the same shape as the create response above. status is one of:

`status`	Meaning
`pending`	Sent, awaiting the patient's response
`approved`	The patient approved the connection. `patientId` is now populated
`expired`	7 days passed with no response

GET /patients/link-requests

Lists your practitioner's link requests.

Query Parameter	Required	Default	Description
`skip`	No	0	Number of records to skip
`limit`	No	10	Max records to retrieve (max: 100)
`patientId`	No	-	Filter to requests for a specific patient
`status`	No	-	Filter by `pending`, `approved`, or `expired`

Response

{
  "total": 3,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": "610ad2a60ae7ef00115c0aa3",
      "patientId": null,
      "status": "pending",
      "createdAt": "2026-08-01T02:00:00.000Z",
      "expiresAt": "2026-08-08T02:00:00.000Z",
      "approvedAt": null
    }
  ]
}

What happens when a patient approves

Approving a connection is more than a permission flag. When the patient accepts, i-screen also:

Updates the patient's notification preferences: allowIscreenPathologyFormNotification and allowIscreenResultsNotification are both set to true for your practitioner going forward, regardless of what they were set to previously.
Unhides the patient's prior test history from your practitioner. Any tests the patient took before this connection, with any practitioner, become visible to you once they approve. This is not limited to tests placed through your practitioner or through the API.

If your integration relies on only seeing tests you placed, filter on your own order/test references rather than assuming a patient's full history reflects only your activity.

note

There is currently no reject action. If a patient does not want to connect, the request simply expires after 7 days with no action needed from them.

Patch a patient

Updates an existing patient's details.

PATCH /patients/:patientId

URL Parameters

Parameter	Description
`patientId`	The patient's record ID

Accepts the same fields as Create a new patient, all optional.

curl -X PATCH https://partner-staging.i-screen.com.au/v1/patients/610ad2a60ae7ef00115c0aa3 \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer f3ee05b1e3d140a3b17456fb69d28cd9-5f6a46513aa48d0bf80a04c7d52c9805633070a7803d3bd4"

Payload

{
  "profile": {
    "phone": "0499999999"
  },
  "healthProfile": {
    "basicInfo": {
      "weight": 72
    }
  }
}

Get a single patient​

URL Parameters​

Get multiple patients​

Query Parameters​

Create a new patient​

Payload​

Existing account​

Requesting a connection to an existing account​

Payload​

If no account exists​

URL Parameters (link request)​

What happens when a patient approves​

Patch a patient​

URL Parameters​

Get a single patient

URL Parameters

Get multiple patients

Query Parameters

Create a new patient

Payload

Existing account

Requesting a connection to an existing account

Payload

If no account exists

URL Parameters (link request)

What happens when a patient approves

Patch a patient

URL Parameters