Update patient - Parchment Health developer docs

PUT

organizations

{organization_id}

users

{user_id}

patients

{patient_id}

cURL

curl --request PUT \
  --url https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients/{patient_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-secret: <x-organization-secret>' \
  --data '
{
  "family_name": "<string>",
  "given_name": "<string>",
  "date_of_birth": "1985-03-15",
  "title": "<string>",
  "phone": "0412345678",
  "email": "jsmith@example.com",
  "ctg_eligible": true,
  "concession_pension_number": "<string>",
  "entitlement_number": "<string>",
  "ihi_number": "<string>",
  "racf_id": "<string>",
  "is_inpatient": true,
  "medicare_card_number": "<string>",
  "medicare_irn": "<string>",
  "medicare_valid_to": "2023-12-25",
  "dva_file_number": "<string>"
}
'

{
  "success": true,
  "statusCode": 200,
  "message": "Patient updated successfully",
  "data": {
    "patient_id": "pat_abc123def456",
    "family_name": "Smith",
    "given_name": "Jane",
    "date_of_birth": "1985-03-15",
    "sex": "F",
    "phone": "0412345678",
    "email": "jane.smith@example.com"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_abc123"
}

Integration Notes

Partial Updates: Only include fields you want to update. Omitted fields will not be modified.
Demographic Updates: Changes to family_name, given_name, date_of_birth, or sex will trigger demographic verification.
Patient Existence: The API will return an error if the patient doesn’t exist in the organization.
Request ID: Always log the requestId for debugging support requests.
DVA Validation: If providing dva_card_color, you must also provide dva_file_number.

Request

Update Basic Patient Information

{
  "phone": "0412345678",
  "email": "patient@example.com"
}

Update Demographics

{
  "given_name": "Jane",
  "family_name": "Smith",
  "date_of_birth": "1985-03-15",
  "sex": "F"
}

Update Medicare Details

{
  "medicare_card_number": "1234567890",
  "medicare_irn": "1",
  "medicare_valid_to": "2025-12-31"
}

Update DVA Details

{
  "dva_file_number": "QSS12345",
  "dva_card_color": "G"
}

Update Address

{
  "australian_address": {
    "street_number": "123",
    "street_name": "Main Street",
    "suburb": "Melbourne",
    "state": "VIC",
    "postcode": "3000"
  }
}

Full Update Example

{
  "title": "Mrs",
  "given_name": "Jane",
  "family_name": "Smith",
  "date_of_birth": "1985-03-15",
  "sex": "F",
  "phone": "0412345678",
  "email": "jane.smith@example.com",
  "medicare_card_number": "1234567890",
  "medicare_irn": "1",
  "medicare_valid_to": "2025-12-31",
  "ctg_eligible": true,
  "indigenous_type": "Neither",
  "ihi_number": "8003608500035100",
  "australian_address": {
    "street_number": "123",
    "street_name": "Main Street",
    "suburb": "Melbourne",
    "state": "VIC",
    "postcode": "3000"
  }
}

Request Fields

Demographic Fields

Field	Type	Required	Description
`family_name`	string	No	Patient’s family/last name
`given_name`	string	No	Patient’s given/first name
`date_of_birth`	string	No	Date of birth in YYYY-MM-DD format
`sex`	string	No	Sex (M/F/I/N)

Basic Fields

Field	Type	Required	Description
`title`	string	No	Patient’s title (Mr, Mrs, Ms, etc.)
`phone`	string	No	Australian phone number
`email`	string	No	Email address
`ctg_eligible`	boolean	No	Closing the Gap eligibility
`indigenous_type`	string	No	Indigenous status
`concession_pension_number`	string	No	Concession/pension card number
`entitlement_number`	string	No	Entitlement number
`ihi_number`	string	No	16-digit Individual Healthcare Identifier
`racf_id`	string	No	Residential Aged Care Facility ID
`is_inpatient`	boolean	No	Whether patient is an inpatient

Medicare Fields

Field	Type	Required	Description
`medicare_card_number`	string	No	Medicare card number (can be null)
`medicare_irn`	string	No	Medicare IRN (numeric only, can be null)
`medicare_valid_to`	string	No	Medicare expiry in YYYY-MM-DD (can be null)

DVA Fields

Field	Type	Required	Description
`dva_file_number`	string	When dva_card_color provided	DVA file number (can be null)
`dva_card_color`	string	No	DVA card color: W/O/G (can be null)

Address Fields

Field	Type	Required	Description
`australian_address`	object	No	Australian address object

Australian Address Object:

Field	Type	Required	Description
`street_number`	string	Yes	Street number (max 12 chars)
`street_name`	string	Yes	Street name (max 100 chars)
`suburb`	string	Yes	Suburb name (max 100 chars)
`state`	string	Yes	Australian state code
`postcode`	string	Yes	4-digit Australian postcode

Enum Values

Sex:

M - Male
F - Female
I - Indeterminate
N - Not stated

Indigenous Type:

Aboriginal
Torres Strait Islander
Both
Neither
Prefer not to say

DVA Card Color:

W - White
O - Orange
G - Gold

Australian States:

VIC, NSW, QLD, WA, SA, TAS, ACT, NT

Response

Success Response (200 OK)

{
  "success": true,
  "statusCode": 200,
  "message": "Patient updated successfully",
  "data": {
    "patient_id": "pat_abc123def456",
    "family_name": "Smith",
    "given_name": "Jane",
    "date_of_birth": "1985-03-15",
    "sex": "F",
    "phone": "0412345678",
    "email": "jane.smith@example.com",
    "medicare_card_number": "1234567890",
    "medicare_irn": "1",
    "medicare_valid_to": "2025-12-31"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_abc123"
}

Validation Error (422 Unprocessable Entity)

{
  "success": false,
  "statusCode": 422,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "validation": [
      {
        "field": "phone",
        "message": "Phone number must be a valid Australian number (e.g., 0412345678, +61412345678)",
        "code": "VALIDATION_ERROR"
      },
      {
        "field": "dva_file_number",
        "message": "DVA card color is provided but DVA file number is missing",
        "code": "VALIDATION_ERROR"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456"
}

Unauthorized (401)

{
  "success": false,
  "statusCode": 401,
  "error": {
    "type": "https://parchment.health/errors/authentication-required",
    "title": "Unauthorized",
    "detail": "Valid authentication token is required"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_ghi789"
}

Insufficient Permissions (403 Forbidden)

{
  "success": false,
  "statusCode": 403,
  "error": {
    "type": "https://parchment.health/errors/insufficient-scope",
    "title": "Insufficient permissions",
    "detail": "This operation requires the 'update:patient' scope"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_jkl012"
}

Internal Server Error (500)

{
  "success": false,
  "statusCode": 500,
  "error": {
    "type": "https://parchment.health/errors/internal-error",
    "title": "Internal server error",
    "detail": "Failed to update patient"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_mno345"
}

Response Fields

Success Response Data

The response returns the updated patient object with all current field values.

Common Response Fields

All responses include these standard fields:

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`statusCode`	number	HTTP status code
`timestamp`	string	ISO 8601 timestamp of the response
`requestId`	string	Unique identifier for debugging

Status Codes

Code	Status	Description
`200`	OK	Patient successfully updated
`400`	Bad Request	Invalid request format or missing required fields
`401`	Unauthorized	Authentication required or token invalid
`403`	Forbidden	Insufficient permissions (missing update:patient scope)
`422`	Unprocessable Entity	Request validation failed
`500`	Internal Server Error	Unexpected server error

Field Validation Requirements

Phone Number Format

The phone field accepts Australian phone numbers in the following formats: Valid Examples:

0412345678 - Mobile number (domestic format)
0312345678 - Landline (domestic format)
61412345678 - International mobile (without + prefix)
+61312345678 - International landline (with + prefix)

Invalid Examples:

0123456789 - Starts with 1 (invalid area code)
04123456789 - Too many digits
04-1234-5678 - Contains formatting characters

String Length Requirements

Street Number: 1-12 characters
Street Name: 1-100 characters
Suburb: 1-100 characters
Postcode: Exactly 4 digits (e.g., “3000”, “2000”)

Medicare IRN

Must contain only numeric digits
Leading/trailing whitespace is automatically trimmed

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-organization-secret

string

required

Organization secret for authentication - provided by Parchment

Path Parameters

organization_id

string<uuid>

required

Organization ID

user_id

string<uuid>

required

User ID

patient_id

string<uuid>

required

Patient ID

Body

application/json

Patient data to update

Patient update request - all fields are optional

family_name

string

Patient's family/last name

given_name

string

Patient's given/first name

date_of_birth

string<date>

Date of birth in YYYY-MM-DD format

Example:

"1985-03-15"

sex

enum<string>

Sex: M (Male), F (Female), I (Indeterminate), N (Not stated)

Available options:

M,

F,

I,

N

title

string

Patient's title (Mr, Mrs, Ms, etc.)

phone

string

Australian phone number

Example:

"0412345678"

string<email>

Email address

ctg_eligible

boolean

Closing the Gap eligibility

indigenous_type

enum<string>

Indigenous status

Available options:

Aboriginal,

Torres Strait Islander,

Both,

Neither,

Prefer not to say

concession_pension_number

string

Concession/pension card number

entitlement_number

string

Entitlement number

ihi_number

string | null

16-digit Individual Healthcare Identifier (IHI). Must be exactly 16 numeric digits.

Pattern: ^\d{16}$

racf_id

string

Residential Aged Care Facility ID

is_inpatient

boolean

Whether patient is an inpatient

medicare_card_number

string | null

Medicare card number

medicare_irn

string | null

Medicare IRN (numeric only)

medicare_valid_to

string<date> | null

Medicare expiry date in YYYY-MM-DD format

dva_file_number

string | null

DVA file number

dva_card_color

enum<string> | null

DVA card color: W (White), O (Orange), G (Gold)

Available options:

W,

O,

G

australian_address

object

Australian address

Show child attributes

Response

Patient updated successfully

success

boolean

required

Indicates if the request was successful

Example:

true

statusCode

integer

required

HTTP status code

Example:

200

message

string

required

Human-readable success message

Example:

"Patient updated successfully"

data

object

required

Updated patient data

timestamp

string<date-time>

required

ISO 8601 timestamp of the response

Example:

"2024-01-15T10:30:00.000Z"

requestId

string

required

Unique identifier for request tracing

Example:

"req_1705312200000_abc123"

pagination

object

Pagination information for list operations

Show child attributes

Get patient prescriptionsGet prescriptions for a specific patient

cURL

curl --request PUT \
  --url https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients/{patient_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-secret: <x-organization-secret>' \
  --data '
{
  "family_name": "<string>",
  "given_name": "<string>",
  "date_of_birth": "1985-03-15",
  "title": "<string>",
  "phone": "0412345678",
  "email": "jsmith@example.com",
  "ctg_eligible": true,
  "concession_pension_number": "<string>",
  "entitlement_number": "<string>",
  "ihi_number": "<string>",
  "racf_id": "<string>",
  "is_inpatient": true,
  "medicare_card_number": "<string>",
  "medicare_irn": "<string>",
  "medicare_valid_to": "2023-12-25",
  "dva_file_number": "<string>"
}
'

{
  "success": true,
  "statusCode": 200,
  "message": "Patient updated successfully",
  "data": {
    "patient_id": "pat_abc123def456",
    "family_name": "Smith",
    "given_name": "Jane",
    "date_of_birth": "1985-03-15",
    "sex": "F",
    "phone": "0412345678",
    "email": "jane.smith@example.com"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_abc123"
}

​Integration Notes

​Request

​Update Basic Patient Information

​Update Demographics

​Update Medicare Details

​Update DVA Details

​Update Address

​Full Update Example

​Request Fields

​Demographic Fields

​Basic Fields

​Medicare Fields

​DVA Fields

​Address Fields

​Enum Values

​Response

​Success Response (200 OK)

​Validation Error (422 Unprocessable Entity)

​Unauthorized (401)

​Insufficient Permissions (403 Forbidden)

​Internal Server Error (500)

​Response Fields

​Success Response Data

​Common Response Fields

​Status Codes

​Field Validation Requirements

​Phone Number Format

​String Length Requirements

​Medicare IRN

Authorizations

Headers

Path Parameters

Body

Response

Integration Notes

Request

Update Basic Patient Information

Update Demographics

Update Medicare Details

Update DVA Details

Update Address

Full Update Example

Request Fields

Demographic Fields

Basic Fields

Medicare Fields

DVA Fields

Address Fields

Enum Values

Response

Success Response (200 OK)

Validation Error (422 Unprocessable Entity)

Unauthorized (401)

Insufficient Permissions (403 Forbidden)

Internal Server Error (500)

Response Fields

Success Response Data

Common Response Fields

Status Codes

Field Validation Requirements

Phone Number Format

String Length Requirements

Medicare IRN