Create patient

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 '
{
  "partner_patient_id": "PMS-000123",
  "partner_id": "demo",
  "given_name": "Denice",
  "family_name": "SHEA",
  "date_of_birth": "1992-12-16",
  "sex": "F",
  "medicare_card_number": "6951907501",
  "medicare_irn": "1",
  "phone": "0417903853",
  "email": "919@Ausnet.com.au",
  "australian_street_address": {
    "street_number": "163",
    "street_name": "Law Rd",
    "suburb": "Jitarning",
    "state": "WA",
    "postcode": "6365"
  }
}
'

import requests

url = "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients"

payload = {
    "partner_patient_id": "PMS-000123",
    "partner_id": "demo",
    "given_name": "Denice",
    "family_name": "SHEA",
    "date_of_birth": "1992-12-16",
    "sex": "F",
    "medicare_card_number": "6951907501",
    "medicare_irn": "1",
    "phone": "0417903853",
    "email": "919@Ausnet.com.au",
    "australian_street_address": {
        "street_number": "163",
        "street_name": "Law Rd",
        "suburb": "Jitarning",
        "state": "WA",
        "postcode": "6365"
    }
}
headers = {
    "x-organization-secret": "<x-organization-secret>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-secret': '<x-organization-secret>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    partner_patient_id: 'PMS-000123',
    partner_id: 'demo',
    given_name: 'Denice',
    family_name: 'SHEA',
    date_of_birth: '1992-12-16',
    sex: 'F',
    medicare_card_number: '6951907501',
    medicare_irn: '1',
    phone: '0417903853',
    email: '919@Ausnet.com.au',
    australian_street_address: {
      street_number: '163',
      street_name: 'Law Rd',
      suburb: 'Jitarning',
      state: 'WA',
      postcode: '6365'
    }
  })
};

fetch('https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'partner_patient_id' => 'PMS-000123',
    'partner_id' => 'demo',
    'given_name' => 'Denice',
    'family_name' => 'SHEA',
    'date_of_birth' => '1992-12-16',
    'sex' => 'F',
    'medicare_card_number' => '6951907501',
    'medicare_irn' => '1',
    'phone' => '0417903853',
    'email' => '919@Ausnet.com.au',
    'australian_street_address' => [
        'street_number' => '163',
        'street_name' => 'Law Rd',
        'suburb' => 'Jitarning',
        'state' => 'WA',
        'postcode' => '6365'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-secret: <x-organization-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients"

	payload := strings.NewReader("{\n  \"partner_patient_id\": \"PMS-000123\",\n  \"partner_id\": \"demo\",\n  \"given_name\": \"Denice\",\n  \"family_name\": \"SHEA\",\n  \"date_of_birth\": \"1992-12-16\",\n  \"sex\": \"F\",\n  \"medicare_card_number\": \"6951907501\",\n  \"medicare_irn\": \"1\",\n  \"phone\": \"0417903853\",\n  \"email\": \"919@Ausnet.com.au\",\n  \"australian_street_address\": {\n    \"street_number\": \"163\",\n    \"street_name\": \"Law Rd\",\n    \"suburb\": \"Jitarning\",\n    \"state\": \"WA\",\n    \"postcode\": \"6365\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-organization-secret", "<x-organization-secret>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients")
  .header("x-organization-secret", "<x-organization-secret>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"partner_patient_id\": \"PMS-000123\",\n  \"partner_id\": \"demo\",\n  \"given_name\": \"Denice\",\n  \"family_name\": \"SHEA\",\n  \"date_of_birth\": \"1992-12-16\",\n  \"sex\": \"F\",\n  \"medicare_card_number\": \"6951907501\",\n  \"medicare_irn\": \"1\",\n  \"phone\": \"0417903853\",\n  \"email\": \"919@Ausnet.com.au\",\n  \"australian_street_address\": {\n    \"street_number\": \"163\",\n    \"street_name\": \"Law Rd\",\n    \"suburb\": \"Jitarning\",\n    \"state\": \"WA\",\n    \"postcode\": \"6365\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-organization-secret"] = '<x-organization-secret>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"partner_patient_id\": \"PMS-000123\",\n  \"partner_id\": \"demo\",\n  \"given_name\": \"Denice\",\n  \"family_name\": \"SHEA\",\n  \"date_of_birth\": \"1992-12-16\",\n  \"sex\": \"F\",\n  \"medicare_card_number\": \"6951907501\",\n  \"medicare_irn\": \"1\",\n  \"phone\": \"0417903853\",\n  \"email\": \"919@Ausnet.com.au\",\n  \"australian_street_address\": {\n    \"street_number\": \"163\",\n    \"street_name\": \"Law Rd\",\n    \"suburb\": \"Jitarning\",\n    \"state\": \"WA\",\n    \"postcode\": \"6365\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Patient already exists",
  "code": "SUCCESS",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "parchment_patient_id": "pat_abc123def456",
    "url": "https://app.parchment.health/dashboard/patients/pat_abc123def456"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_stu901"
}

{
  "success": true,
  "statusCode": 201,
  "message": "Patient created successfully",
  "code": "SUCCESS",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "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"
}

{
  "success": true,
  "statusCode": 202,
  "message": "Patient creation accepted - conflicts found",
  "code": "PATIENT_CREATED_CONFLICTS_FOUND",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "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"
}

{
  "success": false,
  "statusCode": 400,
  "code": "INVALID_USER_PARAMETERS",
  "error": {
    "type": "https://parchment.health/errors/invalid-request",
    "title": "Invalid request",
    "detail": "IHI already assigned to another patient"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_mno345"
}

{
  "success": false,
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "error": {
    "type": "https://parchment.health/errors/authentication-required",
    "title": "Unauthorized",
    "detail": "Insufficient scope"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_pqr678"
}

{
  "success": false,
  "statusCode": 409,
  "code": "USER_ALREADY_EXISTS",
  "error": {
    "type": "https://parchment.health/errors/resource-conflict",
    "title": "Resource conflict",
    "detail": "Patient already exists"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_ghi789"
}

{
  "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 is required",
        "code": "VALIDATION_ERROR"
      },
      {
        "field": "date_of_birth",
        "message": "Date of birth is required",
        "code": "VALIDATION_ERROR"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_jkl012",
  "code": "VALIDATION_ERROR"
}

{
  "success": false,
  "statusCode": 500,
  "code": "INTERNAL_ERROR",
  "error": {
    "type": "https://parchment.health/errors/internal-error",
    "title": "Internal server error",
    "detail": "Something went wrong, please try again later"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_yza567"
}

Overview

Creates a patient in the organization. Parchment searches the HI Service for the IHI. A supplied ihi_number is searched first. A repeat partner_patient_id is idempotent. No new patient is created and the existing patient is returned with 200. Requires the create:patient scope.

Request Example

{
  "partner_patient_id": "PMS-000123",
  "partner_id": "demo",
  "given_name": "Denice",
  "family_name": "SHEA",
  "date_of_birth": "1992-12-16",
  "sex": "F",
  "medicare_card_number": "6951907501",
  "medicare_irn": "1",
  "phone": "0417903853",
  "email": "919@Ausnet.com.au",
  "australian_street_address": {
    "street_number": "163",
    "street_name": "Law Rd",
    "suburb": "Jitarning",
    "state": "WA",
    "postcode": "6365"
  }
}

Response Examples

Created (201)

{
  "success": true,
  "statusCode": 201,
  "message": "Patient created successfully",
  "code": "SUCCESS",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "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"
}

Already Exists (200)

{
  "success": true,
  "statusCode": 200,
  "message": "Patient already exists",
  "code": "SUCCESS",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "parchment_patient_id": "pat_abc123def456",
    "url": "https://app.parchment.health/dashboard/patients/pat_abc123def456"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_stu901"
}

Conflicts Found (202)

{
  "success": true,
  "statusCode": 202,
  "message": "Patient creation accepted - conflicts found",
  "code": "PATIENT_CREATED_CONFLICTS_FOUND",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "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)

{
  "success": false,
  "statusCode": 422,
  "code": "VALIDATION_ERROR",
  "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 is required",
        "code": "VALIDATION_ERROR"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_ghi789"
}

Conflict (409)

{
  "success": false,
  "statusCode": 409,
  "code": "USER_ALREADY_EXISTS",
  "error": {
    "type": "https://parchment.health/errors/resource-conflict",
    "title": "Resource conflict",
    "detail": "Patient already exists"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_jkl012"
}

Response Fields

Field	Type	Description
`external_patient_id`	string	Your `partner_patient_id`, prefixed with your partner ID
`parchment_patient_id`	string	Parchment’s patient ID
`url`	string	Link to the patient in the Parchment portal

Status Codes

Code	Status	Description
`200`	OK	Patient already exists; existing patient returned
`201`	Created	Patient created, or existing patient re-linked
`202`	Accepted	Demographic conflicts found; matching patient returned
`400`	Bad Request	Patient not created, e.g. IHI already assigned
`401`	Unauthorized	Token invalid, or missing `create:patient` scope
`409`	Conflict	Rare: `partner_patient_id` conflict
`422`	Unprocessable Entity	Request validation failed
`500`	Internal Server Error	Unexpected server error

Validation

Field	Rule
`partner_id`	Required. Your registered partner ID, per environment
`partner_patient_id`	Required. 1–150 characters, unique in the organization
`given_name`, `family_name`	Required. Not empty
`phone`	Australian mobile only (`04`/`05`, or `+61`/`61` prefix). Spaces, dashes and brackets are stripped
`ihi_number`	Optional. Exactly 16 digits
`postcode`	Exactly 4 digits
`sex`, `state`	Case-insensitive. `state` also accepts the full name

Notes

Use external_patient_id from the response as the stored ID; a prefixed value is not double-prefixed.
Send australian_street_address or australian_address; both are accepted.
A 201 can return an existing patient: same name, date of birth and sex is re-linked to your partner_patient_id.

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

partner_id

string

required

Your Parchment-assigned partner identifier (lowercase slug, e.g. 'tacklit'). Parchment registers this value during partner onboarding — requests with an unregistered value are rejected with a 422 validation error. Contact Parchment before go-live to have your identifier registered.

Example:

"demo"

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 mobile number (optional). Must be a valid Australian mobile (04xxxxxxxx or 05xxxxxxxx), digits only. International format with +61 or 61 prefix is also accepted. Landlines are rejected. A mobile number can be used for IHI lookup against the Healthcare Identifiers Service.

australian_street_address

object

Show child attributes

australian_address

object

Alias of australian_street_address. Send one, not both.

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

Response

Patient already exists. A repeat partner_patient_id returns the existing patient.

success

boolean

required

Always true

Example:

true

statusCode

enum<integer>

required

201 created, 200 already exists, 202 conflicts found.

Available options:

200,

201,

202

Example:

201

message

string

required

Outcome summary.

Example:

"Patient created successfully"

code

enum<string>

required

Operation code.

Available options:

SUCCESS,

PATIENT_CREATED_CONFLICTS_FOUND

Example:

"SUCCESS"

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"

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 '
{
  "partner_patient_id": "PMS-000123",
  "partner_id": "demo",
  "given_name": "Denice",
  "family_name": "SHEA",
  "date_of_birth": "1992-12-16",
  "sex": "F",
  "medicare_card_number": "6951907501",
  "medicare_irn": "1",
  "phone": "0417903853",
  "email": "919@Ausnet.com.au",
  "australian_street_address": {
    "street_number": "163",
    "street_name": "Law Rd",
    "suburb": "Jitarning",
    "state": "WA",
    "postcode": "6365"
  }
}
'

import requests

url = "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients"

payload = {
    "partner_patient_id": "PMS-000123",
    "partner_id": "demo",
    "given_name": "Denice",
    "family_name": "SHEA",
    "date_of_birth": "1992-12-16",
    "sex": "F",
    "medicare_card_number": "6951907501",
    "medicare_irn": "1",
    "phone": "0417903853",
    "email": "919@Ausnet.com.au",
    "australian_street_address": {
        "street_number": "163",
        "street_name": "Law Rd",
        "suburb": "Jitarning",
        "state": "WA",
        "postcode": "6365"
    }
}
headers = {
    "x-organization-secret": "<x-organization-secret>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-secret': '<x-organization-secret>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    partner_patient_id: 'PMS-000123',
    partner_id: 'demo',
    given_name: 'Denice',
    family_name: 'SHEA',
    date_of_birth: '1992-12-16',
    sex: 'F',
    medicare_card_number: '6951907501',
    medicare_irn: '1',
    phone: '0417903853',
    email: '919@Ausnet.com.au',
    australian_street_address: {
      street_number: '163',
      street_name: 'Law Rd',
      suburb: 'Jitarning',
      state: 'WA',
      postcode: '6365'
    }
  })
};

fetch('https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'partner_patient_id' => 'PMS-000123',
    'partner_id' => 'demo',
    'given_name' => 'Denice',
    'family_name' => 'SHEA',
    'date_of_birth' => '1992-12-16',
    'sex' => 'F',
    'medicare_card_number' => '6951907501',
    'medicare_irn' => '1',
    'phone' => '0417903853',
    'email' => '919@Ausnet.com.au',
    'australian_street_address' => [
        'street_number' => '163',
        'street_name' => 'Law Rd',
        'suburb' => 'Jitarning',
        'state' => 'WA',
        'postcode' => '6365'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-secret: <x-organization-secret>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients"

	payload := strings.NewReader("{\n  \"partner_patient_id\": \"PMS-000123\",\n  \"partner_id\": \"demo\",\n  \"given_name\": \"Denice\",\n  \"family_name\": \"SHEA\",\n  \"date_of_birth\": \"1992-12-16\",\n  \"sex\": \"F\",\n  \"medicare_card_number\": \"6951907501\",\n  \"medicare_irn\": \"1\",\n  \"phone\": \"0417903853\",\n  \"email\": \"919@Ausnet.com.au\",\n  \"australian_street_address\": {\n    \"street_number\": \"163\",\n    \"street_name\": \"Law Rd\",\n    \"suburb\": \"Jitarning\",\n    \"state\": \"WA\",\n    \"postcode\": \"6365\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-organization-secret", "<x-organization-secret>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients")
  .header("x-organization-secret", "<x-organization-secret>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"partner_patient_id\": \"PMS-000123\",\n  \"partner_id\": \"demo\",\n  \"given_name\": \"Denice\",\n  \"family_name\": \"SHEA\",\n  \"date_of_birth\": \"1992-12-16\",\n  \"sex\": \"F\",\n  \"medicare_card_number\": \"6951907501\",\n  \"medicare_irn\": \"1\",\n  \"phone\": \"0417903853\",\n  \"email\": \"919@Ausnet.com.au\",\n  \"australian_street_address\": {\n    \"street_number\": \"163\",\n    \"street_name\": \"Law Rd\",\n    \"suburb\": \"Jitarning\",\n    \"state\": \"WA\",\n    \"postcode\": \"6365\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}/patients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-organization-secret"] = '<x-organization-secret>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"partner_patient_id\": \"PMS-000123\",\n  \"partner_id\": \"demo\",\n  \"given_name\": \"Denice\",\n  \"family_name\": \"SHEA\",\n  \"date_of_birth\": \"1992-12-16\",\n  \"sex\": \"F\",\n  \"medicare_card_number\": \"6951907501\",\n  \"medicare_irn\": \"1\",\n  \"phone\": \"0417903853\",\n  \"email\": \"919@Ausnet.com.au\",\n  \"australian_street_address\": {\n    \"street_number\": \"163\",\n    \"street_name\": \"Law Rd\",\n    \"suburb\": \"Jitarning\",\n    \"state\": \"WA\",\n    \"postcode\": \"6365\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "statusCode": 200,
  "message": "Patient already exists",
  "code": "SUCCESS",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "parchment_patient_id": "pat_abc123def456",
    "url": "https://app.parchment.health/dashboard/patients/pat_abc123def456"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_stu901"
}

{
  "success": true,
  "statusCode": 201,
  "message": "Patient created successfully",
  "code": "SUCCESS",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "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"
}

{
  "success": true,
  "statusCode": 202,
  "message": "Patient creation accepted - conflicts found",
  "code": "PATIENT_CREATED_CONFLICTS_FOUND",
  "data": {
    "external_patient_id": "DEMO#PMS-000123",
    "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"
}

{
  "success": false,
  "statusCode": 400,
  "code": "INVALID_USER_PARAMETERS",
  "error": {
    "type": "https://parchment.health/errors/invalid-request",
    "title": "Invalid request",
    "detail": "IHI already assigned to another patient"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_mno345"
}

{
  "success": false,
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "error": {
    "type": "https://parchment.health/errors/authentication-required",
    "title": "Unauthorized",
    "detail": "Insufficient scope"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_pqr678"
}

{
  "success": false,
  "statusCode": 409,
  "code": "USER_ALREADY_EXISTS",
  "error": {
    "type": "https://parchment.health/errors/resource-conflict",
    "title": "Resource conflict",
    "detail": "Patient already exists"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_ghi789"
}

{
  "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 is required",
        "code": "VALIDATION_ERROR"
      },
      {
        "field": "date_of_birth",
        "message": "Date of birth is required",
        "code": "VALIDATION_ERROR"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_jkl012",
  "code": "VALIDATION_ERROR"
}

{
  "success": false,
  "statusCode": 500,
  "code": "INTERNAL_ERROR",
  "error": {
    "type": "https://parchment.health/errors/internal-error",
    "title": "Internal server error",
    "detail": "Something went wrong, please try again later"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_yza567"
}

API Documentation

Authentication

Authentication Endpoints

Patient Management Endpoints

User Management Endpoints

Custom Drug Endpoints

Overview

Request Example

Response Examples

Created (201)

Already Exists (200)

Conflicts Found (202)

Validation Error (422)

Conflict (409)

Response Fields

Status Codes

Validation

Notes

Authorizations

Headers

Path Parameters

Body

Response

​Overview

​Request Example

​Response Examples

​Created (201)

​Already Exists (200)

​Conflicts Found (202)

​Validation Error (422)

​Conflict (409)

​Response Fields

​Status Codes

​Validation

​Notes

Authorizations

Headers

Path Parameters

Body

Response

Overview

Request Example

Response Examples

Created (201)

Already Exists (200)

Conflicts Found (202)

Validation Error (422)

Conflict (409)

Response Fields

Status Codes

Validation

Notes