Create patient - Parchment Health developer docs

POST

organizations

{organization_id}

users

{user_id}

patients

cURL

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

{
  "success": true,
  "statusCode": 201,
  "message": "Patient created successfully",
  "data": {
    "external_patient_id": "PARTNER#12345",
    "parchment_patient_id": "pat_abc123def456",
    "url": "https://app.parchment.health/dashboard/patients/pat_abc123def456"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_abc123"
}

Response Examples

Success Response (201 Created)

{
  "success": true,
  "statusCode": 201,
  "message": "Patient created successfully",
  "data": {
    "external_patient_id": "CLINIKO#12345",
    "parchment_patient_id": "pat_abc123def456",
    "url": "https://app.parchment.health/dashboard/patients/pat_abc123def456"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_abc123"
}

Conflict Detected (202 Accepted)

{
  "success": true,
  "statusCode": 202,
  "message": "Patient creation accepted - conflicts found",
  "data": {
    "external_patient_id": "CLINIKO#12345",
    "parchment_patient_id": "pat_existing789",
    "url": "https://app.parchment.health/dashboard/patients/pat_existing789"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456"
}

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": "family_name",
        "message": "Family name cannot be empty",
        "code": "VALIDATION_ERROR"
      },
      {
        "field": "given_name",
        "message": "Given name cannot be empty",
        "code": "VALIDATION_ERROR"
      },
      {
        "field": "phone",
        "message": "Phone number must be a valid Australian number (e.g., 0412345678, +61412345678)",
        "code": "INVALID_FORMAT"
      },
      {
        "field": "postcode",
        "message": "Postcode must be 4 digits",
        "code": "INVALID_FORMAT"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_ghi789"
}

Partner Patient ID Conflict (409 Conflict)

{
  "success": false,
  "statusCode": 409,
  "error": {
    "type": "https://parchment.health/errors/partner-patient-id-conflict",
    "title": "Partner patient ID conflict",
    "detail": "Partner patient ID 'CLINIKO#12345' is already in use by another patient. Please use a unique identifier."
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_jkl012"
}

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_mno345"
}

Insufficient Permissions (403 Forbidden)

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

Response Fields

Success Response Data

Field	Type	Description
`external_patient_id`	string	Your system’s patient identifier (as provided in request)
`parchment_patient_id`	string	Parchment’s unique patient identifier
`url`	string	Direct link to patient in Parchment portal

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
`201`	Created	Patient successfully created
`202`	Accepted	Patient creation accepted (demographic conflicts found)
`400`	Bad Request	Invalid request format or missing required fields
`401`	Unauthorized	Authentication required or token invalid
`403`	Forbidden	Insufficient permissions (missing CREATE_PATIENT scope)
`409`	Conflict	Partner patient ID already exists
`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 - Melbourne landline (domestic format)
0212345678 - Sydney landline (domestic format)
0712345678 - Brisbane landline (domestic format)
0812345678 - Adelaide 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
041234567 - Too few digits
04-1234-5678 - Contains formatting characters
+1234567890 - Non-Australian number

IHI Number

The ihi_number field is an optional 16-digit Individual Healthcare Identifier.

If provided, it must be exactly 16 numeric digits (e.g., "8003608500035100").
If omitted, Parchment will attempt to fetch the IHI automatically from the HI Service using the patient’s demographics and Medicare/DVA details.

String Length Requirements

Family Name: 1-255 characters, cannot be empty
Given Name: 1-255 characters, cannot be empty
Partner Patient ID: 1-150 characters, must be unique
Street Number: 1-12 characters
Street Name: 1-100 characters
Suburb: 1-100 characters
Postcode: Exactly 4 digits (e.g., “3000”, “2000”)

Integration Notes

Store Request ID: Always log the requestId for debugging support requests
Handle 202 Status: A 202 response indicates demographic conflicts were found but a matching patient was returned
Validation Errors: Use the error.validation array to display field-specific error messages
Partner Patient ID: Must be unique across your organization; use the format returned in external_patient_id
URL Access: The returned url provides direct access to the patient in the Parchment portal
Phone Validation: Phone numbers must follow Australian format - see validation requirements above
IHI Lookup: Omit ihi_number to have Parchment resolve it via the HI Service; provide it explicitly only when you already hold a verified 16-digit IHI

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

Body

application/json

Patient data to add to Parchment

Patient information to be created

given_name

string

required

Patient's given name

family_name

string

required

Patient's family name

date_of_birth

string<date>

required

Patient's date of birth in YYYY-MM-DD format

sex

enum<string>

required

Patient's sex

Available options:

M,

F,

N,

I

partner_patient_id

string

required

Partner's unique identifier for the patient

dva_file_number

string

DVA file number

ihi_number

string

16-digit Individual Healthcare Identifier (IHI). If omitted, Parchment will attempt to fetch it from the HI Service.

medicare_card_number

string

Medicare card number

medicare_irn

string

Medicare IRN

string<email>

Patient's email address (optional)

phone

string

Patient's Australian phone number (optional). Must be a valid Australian number with digits only. Supports mobile (04xxxxxxxx) and landline (0[2378]xxxxxxxx) formats. International format with +61 or 61 prefix is also accepted.

australian_address

object

Show child attributes

medicare_valid_to

string<date>

Medicare card expiry date

concession_pension_number

string

Concession or pension number

entitlement_number

string

Entitlement number

dva_card_color

enum<string>

DVA card color

Available options:

gold,

white,

orange

racf_id

string

RACF identifier

ctg_eligible

boolean

Closing the Gap eligibility

indigenous_type

enum<string>

Patient's indigenous status

Available options:

aboriginal,

torres_strait_islander,

both,

neither,

not_stated

partner_id

string

Partner's unique identifier for the organization

Response

Patient created successfully

success

boolean

required

Indicates if the request was successful

Example:

true

statusCode

integer

required

HTTP status code

Example:

201

message

string

required

Human-readable success message

Example:

"Patient created successfully"

data

object

required

Patient creation response data

Show child attributes

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

Update patientUpdates an existing patient in Parchment

cURL

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

{
  "success": true,
  "statusCode": 201,
  "message": "Patient created successfully",
  "data": {
    "external_patient_id": "PARTNER#12345",
    "parchment_patient_id": "pat_abc123def456",
    "url": "https://app.parchment.health/dashboard/patients/pat_abc123def456"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_abc123"
}

​Response Examples

​Success Response (201 Created)

​Conflict Detected (202 Accepted)

​Validation Error (422 Unprocessable Entity)

​Partner Patient ID Conflict (409 Conflict)

​Unauthorized (401)

​Insufficient Permissions (403 Forbidden)

​Response Fields

​Success Response Data

​Common Response Fields

​Status Codes

​Field Validation Requirements

​Phone Number Format

​IHI Number

​String Length Requirements

​Integration Notes

Authorizations

Headers

Path Parameters

Body

Response

Response Examples

Success Response (201 Created)

Conflict Detected (202 Accepted)

Validation Error (422 Unprocessable Entity)

Partner Patient ID Conflict (409 Conflict)

Unauthorized (401)

Insufficient Permissions (403 Forbidden)

Response Fields

Success Response Data

Common Response Fields

Status Codes

Field Validation Requirements

Phone Number Format

IHI Number

String Length Requirements

Integration Notes