Skip to main content
GET
/
v1
/
organizations
/
{organization_id}
/
users
/
{user_id}
cURL
curl --request GET \
  --url https://api.dev.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": "[email protected]",
    "full_name": "Dr Darlene Cameron",
    "access_roles": ["admin", "provider"],
    "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": "[email protected]",
    "full_name": "John Smith",
    "access_roles": ["admin"]
  },
  "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

FieldTypeDescription
user_idstringParchment’s unique user identifier
emailstringUser’s email address
full_namestringUser’s full display name
access_rolesarrayArray of user roles (admin, provider, etc.)
titlestringProfessional title (optional)
erx_entity_idstringElectronic prescription entity ID (optional)
provider_detailsobjectProvider-specific details (only if user has “provider” role)

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

FieldTypeDescription
hpii_numberstringHealthcare Provider Individual Identifier
prescriber_numberstringPrescriber number
prescriber_typestringPrescriber type (M/N/D/P/T)
ahpra_numberstringAHPRA registration number
qualificationsstringProfessional qualifications
hospital_provider_numberstringHospital provider number
family_namestringProvider’s family name
given_namestringProvider’s given name
date_of_birthstringDate of birth (YYYY-MM-DD format)
sexstringSex (M/F/I/O)
phonestringAustralian phone number
australian_addressobjectProvider’s Australian address

​
Australian Address Object

FieldTypeDescription
street_numberstringStreet number
street_namestringStreet name
suburbstringSuburb
statestringAustralian state
postcodestringAustralian postcode

​
Common Response Fields

All responses include these standard fields:
FieldTypeDescription
successbooleanIndicates if the request was successful
statusCodenumberHTTP status code
timestampstringISO 8601 timestamp of the response
requestIdstringUnique identifier for debugging

​
Path Parameters

ParameterTypeRequiredDescription
organization_idstringYesOrganization identifier
user_idstringYesUser identifier

​
Status Codes

CodeStatusDescription
200OKUser details retrieved successfully
400Bad RequestInvalid request format or missing parameters
401UnauthorizedAuthentication required or token invalid or scope invalid
404Not FoundUser not found
500Internal Server ErrorUnexpected server error

​
Integration Notes

  1. Store Request ID: Always log the requestId for debugging support requests
  2. Handle 404 Status: Check if the user exists before attempting to read
  3. Permission Requirements: Ensure your API token has the READ_USER scope
  4. Organization Access: You can only read users from organizations you have access to
  5. Provider Data Availability: If provider details cannot be retrieved, provider_details will be null
  6. Caching: Consider caching user data with appropriate TTL to reduce API calls
  7. 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