Create patient

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

Error Handling

Recommended Approach

async function createPatient(patientData) {
  try {
    const response = await fetch(
      "/v1/organizations/org123/users/user456/patients",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer your_jwt_token",
          "Content-Type": "application/json",
        },
        body: JSON.stringify(patientData),
      }
    );

    const result = await response.json();

    if (result.success) {
      // Handle success
      console.log("Patient created:", result.data.parchment_patient_id);
      return result.data;
    } else {
      // Handle error
      console.error("Error:", result.error.detail);

      // Handle specific error types
      switch (result.statusCode) {
        case 422:
          // Show validation errors
          result.error.validation.forEach((err) => {
            console.error(`${err.field}: ${err.message}`);
          });
          break;
        case 409:
          // Handle partner patient ID conflict
          console.error("Patient ID already exists");
          break;
        case 401:
          // Handle authentication error
          console.error("Please log in again");
          break;
        default:
          console.error("Unexpected error occurred");
      }

      // Always log requestId for debugging
      console.log("Request ID:", result.requestId);
    }
  } catch (error) {
    console.error("Network error:", 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

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-5 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

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

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_street_address

object

Show child attributes

australian_street_address.street_number

string

required

Street number

australian_street_address.street_name

string

required

Street name

australian_street_address.suburb

string

required

Suburb

australian_street_address.state

enum<string>

required

Australian state or territory

Available options:

NSW,

VIC,

QLD,

WA,

SA,

TAS,

ACT,

NT

australian_street_address.postcode

string

required

Australian postcode (4 digits)

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

Response payload data Patient creation response data

Show child attributes

data.external_patient_id

string

required

Partner's unique identifier for the patient

Example:

"PARTNER#12345"

data.parchment_patient_id

string

required

Parchment's unique identifier for the patient

Example:

"pat_abc123def456"

data.url

string<uri>

required

URL to access the patient in Parchment portal

Example:

"https://app.parchment.health/dashboard/patients/pat_abc123def456"

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

pagination.count

integer

Number of items in current response

pagination.hasNext

boolean

Whether more items are available

pagination.limit

integer

Maximum items per page

pagination.offset

integer

Starting position of current page

pagination.lastKey

string | null

Opaque cursor for fetching the next page. Use this value as the lastKey query parameter for the next request. If null, no more pages are available

API Documentation

Authentication

Authentication Endpoints

Patient Management Endpoints

User Management Endpoints

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

Error Handling

Recommended Approach

Field Validation Requirements

Phone Number Format

String Length Requirements

Integration Notes

Authorizations

Headers

Path Parameters

Body

Response

API Documentation

Authentication

Authentication Endpoints

Patient Management Endpoints

User Management Endpoints

​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

​Error Handling

​Recommended Approach

​Field Validation Requirements

​Phone Number Format

​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

Error Handling

Recommended Approach

Field Validation Requirements

Phone Number Format

String Length Requirements

Integration Notes