> ## 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 users

> Retrieves all users in an organization from Parchment

## Response Examples

### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Retrieved 3 users successfully",
  "data": [
    {
      "user_id": "usr_abc123def456",
      "email": "darlene.cameron@example.com"
    },
    {
      "user_id": "usr_def456ghi789",
      "email": "john.smith@example.com"
    },
    {
      "user_id": "usr_ghi789jkl012",
      "email": "sarah.jones@example.com"
    }
  ],
  "timestamp": "2024-01-25T09:15:00.000Z",
  "requestId": "req_1706171700000_abc123"
}
```

### Empty Organization (200 OK)

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Retrieved 0 users successfully",
  "data": [],
  "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": "Organization 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

The response returns an array of user objects, where each user contains:

| Field     | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| `user_id` | string | Parchment's unique user identifier |
| `email`   | string | User's email address               |

**Note**: This endpoint only returns basic user identification fields (`user_id` and `email`) for security and performance reasons. Use the read-user endpoint to get detailed information about a specific user.

### 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                        |
| `message`    | string  | Human-readable status message           |
| `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 |

## Status Codes

| Code  | Status                | Description                                               |
| ----- | --------------------- | --------------------------------------------------------- |
| `200` | OK                    | Users retrieved successfully (including empty list)       |
| `400` | Bad Request           | Invalid request format or missing parameters              |
| `401` | Unauthorized          | Authentication required or token invalid or scope invalid |
| `500` | Internal Server Error | Unexpected server error                                   |

## Error Handling

## Integration Notes

1. **Store Request ID**: Always log the `requestId` for debugging support requests
2. **Handle Empty Results**: The API returns an empty array if no users are found
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. **Limited Data**: Only `user_id` and `email` are returned for security and performance reasons
6. **Detailed Information**: Use the read-user endpoint (`GET /users/{user_id}`) to get full user details
7. **Pagination**: This endpoint returns all users in the organization (no pagination currently)
8. **Caching**: Consider caching user lists with appropriate TTL to reduce API calls


## OpenAPI

````yaml GET /v1/organizations/{organization_id}/users
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:
    get:
      description: Retrieves all users in an organization 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: limit
          in: query
          required: false
          description: Maximum number of users to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: lastKey
          in: query
          required: false
          description: Pagination key for retrieving the next set of results
          schema:
            type: string
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: 3c006fa3-fee1-472c-9b57-3132a7246cf8
              example:
                success: true
                statusCode: 200
                message: Users retrieved successfully
                data:
                  users:
                    - user_id: usr_abc123def456
                      external_user_id: PARTNER#USER_12345
                      full_name: John Doe
                      access_roles:
                        - provider
                        - admin
                  pagination:
                    total: 1
                    limit: 20
                    lastKey: null
                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'
        '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

````