> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parchmenthealth.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read user

> Retrieves a specific user from Parchment

## Response Examples

### Success Response - Provider User (200 OK)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

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


## OpenAPI

````yaml GET /v1/organizations/{organization_id}/users/{user_id}
openapi: 3.0.1
info:
  title: Parchment APIs
  description: >-
    Parchments API documentation for partner integrations, enabling secure
    e-prescription services
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.sandbox.parchmenthealth.io/external
  - url: https://api.parchmenthealth.io/external
security:
  - bearerAuth: []
paths:
  /v1/organizations/{organization_id}/users/{user_id}:
    get:
      description: Retrieves a specific user from Parchment
      parameters:
        - name: x-organization-secret
          in: header
          required: true
          description: Organization secret for authentication - provided by Parchment
          schema:
            type: string
        - name: organization_id
          in: path
          required: true
          description: Organization ID
          schema:
            type: string
            format: uuid
        - name: user_id
          in: path
          required: true
          description: User ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                $ref: 5aa86cc7-e135-4134-aafe-8a6e3cc25048
              example:
                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
        '400':
          description: Bad Request - Invalid request format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApiErrorResponse'
        '401':
          description: Unauthorized - Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApiErrorResponse'
        '403':
          description: Forbidden - Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApiErrorResponse'
        '404':
          description: Not Found - User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalApiErrorResponse'
components:
  schemas:
    ExternalApiErrorResponse:
      type: object
      required:
        - success
        - statusCode
        - error
        - timestamp
        - requestId
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
          example: false
        statusCode:
          type: integer
          description: HTTP status code
          example: 400
        code:
          type: string
          description: Machine-readable operation code identifying the error
          example: RESOURCE_NOT_FOUND
        error:
          type: object
          description: RFC 7807 compliant error details
          required:
            - type
            - title
            - detail
          properties:
            type:
              type: string
              format: uri
              description: URI identifying the problem type
              example: https://parchment.health/errors/validation-error
            title:
              type: string
              description: Human-readable summary of the problem
              example: Validation failed
            detail:
              type: string
              description: Human-readable explanation of the problem
              example: There were some problems with your input.
            instance:
              type: string
              format: uri
              description: URI reference to the specific occurrence
              example: /patients/123
            validation:
              type: array
              description: Field-level validation errors (for 422 responses)
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: Field name that failed validation
                  message:
                    type: string
                    description: Validation error message
                  code:
                    type: string
                    description: Error code for programmatic handling
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
          example: '2024-01-15T10:30:00.000Z'
        requestId:
          type: string
          description: Unique identifier for request tracing
          example: req_1705312200000_def456
        meta:
          type: object
          description: Additional response metadata
          properties:
            apiVersion:
              type: string
              description: API version used
              example: '1.0'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````