User Management Endpoints
Read user
Retrieves a specific user from Parchment
GET
/
v1
/
organizations
/
{organization_id}
/
users
/
{user_id}
cURL
curl --request GET \
--url https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id} \
--header 'Authorization: Bearer <token>' \
--header 'x-organization-secret: <x-organization-secret>'import requests
url = "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}"
headers = {
"x-organization-secret": "<x-organization-secret>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'x-organization-secret': '<x-organization-secret>',
Authorization: 'Bearer <token>'
}
};
fetch('https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}', 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}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-organization-secret", "<x-organization-secret>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}")
.header("x-organization-secret", "<x-organization-secret>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-organization-secret"] = '<x-organization-secret>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"statusCode": 200,
"message": "User details retrieved successfully",
"code": "SUCCESS",
"data": {
"user_id": "0b4c1a49-fea8-4922-a3da-2ca8ff8af9bd",
"email": "darlene.cameron@example.com",
"full_name": "Darlene Cameron",
"access_roles": [
"admin",
"provider"
],
"details": {
"given_name": "Darlene",
"family_name": "Cameron",
"title": "Dr",
"date_of_birth": "1969-10-02",
"sex": "F"
},
"provider_details": {
"title": "Dr",
"hpii_number": "8003614900029560",
"erx_entity_id": "AB12C",
"prescriber_number": "1234567",
"prescriber_type": "M",
"provider_number": "123456789",
"ahpra_number": "MED0000932846",
"qualifications": "MBBS, FRACGP",
"hospital_provider_number": "H123456",
"family_name": "Cameron",
"given_name": "Darlene",
"date_of_birth": "1969-10-02",
"sex": "F",
"phone": "0412345678",
"australian_address": {
"street_number": "1",
"street_name": "Collins Street",
"suburb": "Melbourne",
"state": "VIC",
"postcode": "3000"
}
}
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "1-68d1b225-2a98752c7b2da3fa489267fc"
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}Response Examples
Success Response - Provider User (200 OK)
{
"success": true,
"statusCode": 200,
"message": "User details retrieved successfully",
"code": "SUCCESS",
"data": {
"user_id": "usr_abc123def456",
"email": "darlene.cameron@example.com",
"full_name": "Dr Darlene Cameron",
"access_roles": ["admin", "provider"],
"details": {
"given_name": "Darlene",
"family_name": "Cameron",
"title": "Dr",
"date_of_birth": "1969-10-02T00:00:00.000Z",
"sex": "F"
},
"provider_details": {
"title": "Dr",
"hpii_number": "8003614900029560",
"erx_entity_id": "F3WFX",
"prescriber_number": "1234567",
"provider_number": "123456",
"prescriber_type": "M",
"ahpra_number": "1234567896321",
"qualifications": "MBBS",
"hospital_provider_number": "H123456",
"family_name": "Cameron",
"given_name": "Darlene",
"date_of_birth": "1969-10-02T00:00:00.000Z",
"sex": "F",
"phone": "0412345678",
"australian_address": {
"street_number": "1",
"street_name": "Collins Street",
"suburb": "Melbourne",
"state": "VIC",
"postcode": "3000"
}
},
"is_escript_ready": {
"can_prescribe": true,
"hpii_verified": true,
"profile_complete": true,
"erx_registered": true,
"mims_ready": true,
"account_enabled": true
}
},
"timestamp": "2024-01-25T09:15:00.000Z",
"requestId": "req_1706171700000_abc123"
}
Success Response - Non-Provider User (200 OK)
{
"success": true,
"statusCode": 200,
"message": "User details retrieved successfully",
"code": "SUCCESS",
"data": {
"user_id": "usr_def456ghi789",
"email": "john.admin@example.com",
"full_name": "John Smith",
"access_roles": ["admin"],
"details": {
"given_name": "John",
"family_name": "Smith",
"title": null,
"date_of_birth": null,
"sex": null
}
},
"timestamp": "2024-01-25T09:15:00.000Z",
"requestId": "req_1706171700000_xyz789"
}
Provider Role, No Provider Record (200 OK)
The user holds theprovider role but has no provider record, so provider_details is null and can_prescribe is false.
{
"success": true,
"statusCode": 200,
"message": "User details retrieved successfully",
"code": "SUCCESS",
"data": {
"user_id": "usr_ghi789jkl012",
"email": "darlene.cameron@example.com",
"full_name": "Darlene Cameron",
"access_roles": ["admin", "provider"],
"details": {
"given_name": "Darlene",
"family_name": "Cameron",
"title": null,
"date_of_birth": null,
"sex": null
},
"provider_details": null,
"is_escript_ready": {
"can_prescribe": false,
"hpii_verified": false,
"profile_complete": false,
"erx_registered": false,
"mims_ready": true,
"account_enabled": true
}
},
"timestamp": "2024-01-25T09:15:00.000Z",
"requestId": "req_1706171700000_pqr901"
}
User Not Found (404 Not Found)
{
"success": false,
"statusCode": 404,
"error": {
"type": "https://parchment.health/errors/user-not-found",
"title": "User not found",
"detail": "User not found"
},
"timestamp": "2024-01-25T09:15:00.000Z",
"requestId": "req_1706171700000_def456"
}
Invalid Parameters (400 Bad Request)
{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/bad-request",
"title": "Bad Request",
"detail": "User ID is required"
},
"timestamp": "2024-01-25T09:15:00.000Z",
"requestId": "req_1706171700000_ghi789"
}
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-25T09:15:00.000Z",
"requestId": "req_1706171700000_jkl012"
}
Insufficient Scope (401 Unauthorized)
{
"success": false,
"statusCode": 401,
"error": {
"type": "https://parchment.health/errors/authentication-required",
"title": "Unauthorized",
"detail": "Insufficient scope"
},
"timestamp": "2024-01-25T09:15:00.000Z",
"requestId": "req_1706171700000_mno345"
}
Checking a prescriber can prescribe
Readis_escript_ready.can_prescribe. It is true only when the user can create an electronic prescription now.
When it is false, the other flags say why:
| Flag | False means |
|---|---|
hpii_verified | HPI-I not confirmed by the HI Service. Send the correct identity to Update User. |
erx_registered | No eRx entity ID yet. Parchment issues it once the profile is verified. |
mims_ready | Medication catalogue still provisioning. Automatic. |
account_enabled | Account is disabled. Re-enable it. |
profile_complete | Prescriber profile incomplete. Advisory only; does not block can_prescribe. |
is_escript_ready is absent for users without the provider or rx_queue_manager role.
There is no
external_user_id or partner_user_id. Map user_id to your own record.Response Fields
Success Response Data
| Field | Type | Description |
|---|---|---|
user_id | string | Parchment’s unique user identifier |
email | string | User’s email address |
full_name | string | User’s full display name |
access_roles | array | Array of user roles (admin, provider, etc.) |
details | object | Core user demographics (always present — see below) |
provider_details | object | null | Provider fields. Present only for provider / rx_queue_manager roles. null means the role is held but no provider record exists |
is_escript_ready | object | Readiness booleans. Present only for provider / rx_queue_manager roles |
Details Object
| Field | Type | Description |
|---|---|---|
given_name | string | null | Provider record first, else split from full_name |
family_name | string | null | Provider record first, else split from full_name |
title | string | null | Professional title |
date_of_birth | string | null | null when no provider record exists |
sex | string | null | null when no provider record exists |
null, never omitted.
Provider Details Object
Every key is always present; an unset value isnull.
| Field | Type | Description |
|---|---|---|
hpii_number | string | Healthcare Provider Individual Identifier |
prescriber_number | string | Prescriber number |
prescriber_type | string | Prescriber type (M/N/D/P/T) |
ahpra_number | string | AHPRA registration number |
qualifications | string | Professional qualifications |
hospital_provider_number | string | Hospital provider number |
family_name | string | Provider’s family name |
given_name | string | Provider’s given name |
date_of_birth | string | Date of birth (YYYY-MM-DD format) |
sex | string | Sex (M/F/I/O) |
phone | string | Australian phone number |
australian_address | object | Provider’s Australian address |
Australian Address Object
| Field | Type | Description |
|---|---|---|
street_number | string | Street number |
street_name | string | Street name |
suburb | string | Suburb |
state | string | Australian state |
postcode | string | Australian postcode |
is_escript_ready Object
| Field | Type | Description |
|---|---|---|
can_prescribe | boolean | User can create an electronic prescription now |
hpii_verified | boolean | HPI-I confirmed against the HI Service |
profile_complete | boolean | Prescriber profile complete. Advisory |
erx_registered | boolean | eRx entity ID issued |
mims_ready | boolean | Medication catalogue provisioned |
account_enabled | boolean | Account is not disabled |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
organization_id | string | Yes | Organization identifier |
user_id | string | Yes | User identifier |
Status Codes
| Code | Status | Description |
|---|---|---|
200 | OK | User details retrieved successfully |
400 | Bad Request | Invalid request format or missing parameters |
401 | Unauthorized | Authentication required or token invalid or scope invalid |
404 | Not Found | User not found |
500 | Internal Server Error | Unexpected server error |
Integration Notes
provider_detailsreflects the user’s role, not their capability. Useis_escript_ready.can_prescribefor that.- Requires the
READ_USERscope. - Log
requestIdfor support requests.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Organization secret for authentication - provided by Parchment
Path Parameters
Organization ID
User ID
Response
User retrieved successfully
Indicates if the request was successful
Example:
true
Example:
200
Example:
"User details retrieved successfully"
Always SUCCESS.
Example:
"SUCCESS"
Full detail for a single user.
Show child attributes
Show child attributes
ISO 8601 timestamp of the response
Example:
"2024-01-15T10:30:00.000Z"
Unique identifier for request tracing
Example:
"req_1705312200000_abc123"
Was this page helpful?
⌘I
cURL
curl --request GET \
--url https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id} \
--header 'Authorization: Bearer <token>' \
--header 'x-organization-secret: <x-organization-secret>'import requests
url = "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}"
headers = {
"x-organization-secret": "<x-organization-secret>",
"Authorization": "Bearer <token>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'x-organization-secret': '<x-organization-secret>',
Authorization: 'Bearer <token>'
}
};
fetch('https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}', 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}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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"
"net/http"
"io"
)
func main() {
url := "https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-organization-secret", "<x-organization-secret>")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}")
.header("x-organization-secret", "<x-organization-secret>")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.parchmenthealth.io/external/v1/organizations/{organization_id}/users/{user_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-organization-secret"] = '<x-organization-secret>'
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"statusCode": 200,
"message": "User details retrieved successfully",
"code": "SUCCESS",
"data": {
"user_id": "0b4c1a49-fea8-4922-a3da-2ca8ff8af9bd",
"email": "darlene.cameron@example.com",
"full_name": "Darlene Cameron",
"access_roles": [
"admin",
"provider"
],
"details": {
"given_name": "Darlene",
"family_name": "Cameron",
"title": "Dr",
"date_of_birth": "1969-10-02",
"sex": "F"
},
"provider_details": {
"title": "Dr",
"hpii_number": "8003614900029560",
"erx_entity_id": "AB12C",
"prescriber_number": "1234567",
"prescriber_type": "M",
"provider_number": "123456789",
"ahpra_number": "MED0000932846",
"qualifications": "MBBS, FRACGP",
"hospital_provider_number": "H123456",
"family_name": "Cameron",
"given_name": "Darlene",
"date_of_birth": "1969-10-02",
"sex": "F",
"phone": "0412345678",
"australian_address": {
"street_number": "1",
"street_name": "Collins Street",
"suburb": "Melbourne",
"state": "VIC",
"postcode": "3000"
}
}
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "1-68d1b225-2a98752c7b2da3fa489267fc"
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}{
"success": false,
"statusCode": 400,
"error": {
"type": "https://parchment.health/errors/validation-error",
"title": "Validation failed",
"detail": "There were some problems with your input.",
"instance": "/patients/123",
"validation": [
{
"field": "<string>",
"message": "<string>",
"code": "<string>"
}
]
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_def456",
"code": "RESOURCE_NOT_FOUND",
"meta": {
"apiVersion": "1.0"
}
}
