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 retrieved successfully",
"data": {
"user_id": "usr_abc123def456",
"external_user_id": "PARTNER#USER_12345",
"full_name": "John Doe",
"access_roles": [
"provider",
"admin"
],
"provider_details": {
"given_name": "John",
"family_name": "Doe",
"prescriber_type": "M",
"prescriber_number": "1234567",
"ahpra_number": "MED0001234567"
}
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_abc123"
}{
"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",
"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"
}
}
},
"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",
"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"
}
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 Permissions (403 Forbidden)
{
"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"
}
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 | Provider-specific details (only if user has “provider” or “rx_queue_manager” role) |
Details Object
| Field | Type | Description |
|---|---|---|
given_name | string | User’s given name |
family_name | string | User’s family name |
title | string | null | Professional title |
date_of_birth | string | null | ISO 8601 timestamp; null for non-provider users |
sex | string | null | M/F/I/O; null for non-provider users |
Provider Details Object (when access_roles includes “provider”)
| 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 |
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 |
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
- Store Request ID: Always log the
requestIdfor debugging support requests - Handle 404 Status: Check if the user exists before attempting to read
- Permission Requirements: Ensure your API token has the
READ_USERscope - Organization Access: You can only read users from organizations you have access to
- Provider Data Availability: If provider details cannot be retrieved,
provider_detailswill benull - Caching: Consider caching user data with appropriate TTL to reduce API calls
- Role-Based Fields: Non-provider users will not have the
provider_detailsfield in the response
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
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 retrieved successfully",
"data": {
"user_id": "usr_abc123def456",
"external_user_id": "PARTNER#USER_12345",
"full_name": "John Doe",
"access_roles": [
"provider",
"admin"
],
"provider_details": {
"given_name": "John",
"family_name": "Doe",
"prescriber_type": "M",
"prescriber_number": "1234567",
"ahpra_number": "MED0001234567"
}
},
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_1705312200000_abc123"
}{
"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"
}
}
