Read user - Parchment Health developer docs

GET

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

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

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 requestId for debugging support requests
Handle 404 Status: Check if the user exists before attempting to read
Permission Requirements: Ensure your API token has the READ_USER scope
Organization Access: You can only read users from organizations you have access to
Provider Data Availability: If provider details cannot be retrieved, provider_details will be null
Caching: Consider caching user data with appropriate TTL to reduce API calls
Role-Based Fields: Non-provider users will not have the provider_details field in the response

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

Response

User retrieved successfully

Read usersRetrieves all users in an organization from Parchment

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

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

​Response Examples

​Success Response - Provider User (200 OK)

​Success Response - Non-Provider User (200 OK)

​User Not Found (404 Not Found)

​Invalid Parameters (400 Bad Request)

​Unauthorized (401)

​Insufficient Permissions (403 Forbidden)

​Response Fields

​Success Response Data

​Details Object

​Provider Details Object (when access_roles includes “provider”)

​Australian Address Object

​Common Response Fields

​Path Parameters

​Status Codes

​Integration Notes

Authorizations

Headers

Path Parameters

Response

Response Examples

Success Response - Provider User (200 OK)

Success Response - Non-Provider User (200 OK)

User Not Found (404 Not Found)

Invalid Parameters (400 Bad Request)

Unauthorized (401)

Insufficient Permissions (403 Forbidden)

Response Fields

Success Response Data

Details Object

Provider Details Object (when access_roles includes “provider”)

Australian Address Object

Common Response Fields

Path Parameters

Status Codes

Integration Notes