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

# Update patient

> Updates an existing patient in Parchment

## Integration Notes

1. **Partial Updates**: Only include fields you want to update. Omitted fields will not be modified.
2. **Demographic Updates**: Changes to `family_name`, `given_name`, `date_of_birth`, or `sex` will trigger demographic verification.
3. **Patient Existence**: The API will return an error if the patient doesn't exist in the organization.
4. **Request ID**: Always log the `requestId` for debugging support requests.
5. **DVA Validation**: If providing `dva_card_color`, you must also provide `dva_file_number`.

## Request

### Update Basic Patient Information

```json theme={null}
{
  "phone": "0412345678",
  "email": "patient@example.com"
}
```

### Update Demographics

```json theme={null}
{
  "given_name": "Jane",
  "family_name": "Smith",
  "date_of_birth": "1985-03-15",
  "sex": "F"
}
```

### Update Medicare Details

```json theme={null}
{
  "medicare_card_number": "1234567890",
  "medicare_irn": "1",
  "medicare_valid_to": "2025-12-31"
}
```

### Update DVA Details

```json theme={null}
{
  "dva_file_number": "QSS12345",
  "dva_card_color": "G"
}
```

### Update Address

```json theme={null}
{
  "australian_address": {
    "street_number": "123",
    "street_name": "Main Street",
    "suburb": "Melbourne",
    "state": "VIC",
    "postcode": "3000"
  }
}
```

### Full Update Example

```json theme={null}
{
  "title": "Mrs",
  "given_name": "Jane",
  "family_name": "Smith",
  "date_of_birth": "1985-03-15",
  "sex": "F",
  "phone": "0412345678",
  "email": "jane.smith@example.com",
  "medicare_card_number": "1234567890",
  "medicare_irn": "1",
  "medicare_valid_to": "2025-12-31",
  "ctg_eligible": true,
  "indigenous_type": "Neither",
  "ihi_number": "8003608500035100",
  "australian_address": {
    "street_number": "123",
    "street_name": "Main Street",
    "suburb": "Melbourne",
    "state": "VIC",
    "postcode": "3000"
  }
}
```

### Request Fields

#### Demographic Fields

| Field           | Type   | Required | Description                        |
| --------------- | ------ | -------- | ---------------------------------- |
| `family_name`   | string | No       | Patient's family/last name         |
| `given_name`    | string | No       | Patient's given/first name         |
| `date_of_birth` | string | No       | Date of birth in YYYY-MM-DD format |
| `sex`           | string | No       | Sex (M/F/I/N)                      |

#### Basic Fields

| Field                       | Type    | Required | Description                               |
| --------------------------- | ------- | -------- | ----------------------------------------- |
| `title`                     | string  | No       | Patient's title (Mr, Mrs, Ms, etc.)       |
| `phone`                     | string  | No       | Australian phone number                   |
| `email`                     | string  | No       | Email address                             |
| `ctg_eligible`              | boolean | No       | Closing the Gap eligibility               |
| `indigenous_type`           | string  | No       | Indigenous status                         |
| `concession_pension_number` | string  | No       | Concession/pension card number            |
| `entitlement_number`        | string  | No       | Entitlement number                        |
| `ihi_number`                | string  | No       | 16-digit Individual Healthcare Identifier |
| `racf_id`                   | string  | No       | Residential Aged Care Facility ID         |
| `is_inpatient`              | boolean | No       | Whether patient is an inpatient           |

#### Medicare Fields

| Field                  | Type   | Required | Description                                 |
| ---------------------- | ------ | -------- | ------------------------------------------- |
| `medicare_card_number` | string | No       | Medicare card number (can be null)          |
| `medicare_irn`         | string | No       | Medicare IRN (numeric only, can be null)    |
| `medicare_valid_to`    | string | No       | Medicare expiry in YYYY-MM-DD (can be null) |

#### DVA Fields

| Field             | Type   | Required                       | Description                         |
| ----------------- | ------ | ------------------------------ | ----------------------------------- |
| `dva_file_number` | string | When dva\_card\_color provided | DVA file number (can be null)       |
| `dva_card_color`  | string | No                             | DVA card color: W/O/G (can be null) |

#### Address Fields

| Field                | Type   | Required | Description               |
| -------------------- | ------ | -------- | ------------------------- |
| `australian_address` | object | No       | Australian address object |

**Australian Address Object:**

| Field           | Type   | Required | Description                  |
| --------------- | ------ | -------- | ---------------------------- |
| `street_number` | string | Yes      | Street number (max 12 chars) |
| `street_name`   | string | Yes      | Street name (max 100 chars)  |
| `suburb`        | string | Yes      | Suburb name (max 100 chars)  |
| `state`         | string | Yes      | Australian state code        |
| `postcode`      | string | Yes      | 4-digit Australian postcode  |

### Enum Values

**Sex:**

* `M` - Male
* `F` - Female
* `I` - Indeterminate
* `N` - Not stated

**Indigenous Type:**

* `Aboriginal`
* `Torres Strait Islander`
* `Both`
* `Neither`
* `Prefer not to say`

**DVA Card Color:**

* `W` - White
* `O` - Orange
* `G` - Gold

**Australian States:**

* `VIC`, `NSW`, `QLD`, `WA`, `SA`, `TAS`, `ACT`, `NT`

## Response

### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Patient updated successfully",
  "data": {
    "patient_id": "pat_abc123def456",
    "family_name": "Smith",
    "given_name": "Jane",
    "date_of_birth": "1985-03-15",
    "sex": "F",
    "phone": "0412345678",
    "email": "jane.smith@example.com",
    "medicare_card_number": "1234567890",
    "medicare_irn": "1",
    "medicare_valid_to": "2025-12-31"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_abc123"
}
```

### Validation Error (422 Unprocessable Entity)

```json theme={null}
{
  "success": false,
  "statusCode": 422,
  "error": {
    "type": "https://parchment.health/errors/validation-error",
    "title": "Validation failed",
    "detail": "There were some problems with your input.",
    "validation": [
      {
        "field": "phone",
        "message": "Phone number must be a valid Australian number (e.g., 0412345678, +61412345678)",
        "code": "VALIDATION_ERROR"
      },
      {
        "field": "dva_file_number",
        "message": "DVA card color is provided but DVA file number is missing",
        "code": "VALIDATION_ERROR"
      }
    ]
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_def456"
}
```

### 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-15T10:30:00.000Z",
  "requestId": "req_1705312200000_ghi789"
}
```

### Insufficient Permissions (403 Forbidden)

```json theme={null}
{
  "success": false,
  "statusCode": 403,
  "error": {
    "type": "https://parchment.health/errors/insufficient-scope",
    "title": "Insufficient permissions",
    "detail": "This operation requires the 'update:patient' scope"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_jkl012"
}
```

### Internal Server Error (500)

```json theme={null}
{
  "success": false,
  "statusCode": 500,
  "error": {
    "type": "https://parchment.health/errors/internal-error",
    "title": "Internal server error",
    "detail": "Failed to update patient"
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "req_1705312200000_mno345"
}
```

## Response Fields

### Success Response Data

The response returns the updated patient object with all current field values.

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

## Status Codes

| Code  | Status                | Description                                             |
| ----- | --------------------- | ------------------------------------------------------- |
| `200` | OK                    | Patient successfully updated                            |
| `400` | Bad Request           | Invalid request format or missing required fields       |
| `401` | Unauthorized          | Authentication required or token invalid                |
| `403` | Forbidden             | Insufficient permissions (missing update:patient scope) |
| `422` | Unprocessable Entity  | Request validation failed                               |
| `500` | Internal Server Error | Unexpected server error                                 |

## Field Validation Requirements

### Phone Number Format

The `phone` field accepts Australian phone numbers in the following formats:

**Valid Examples:**

* `0412345678` - Mobile number (domestic format)
* `0312345678` - Landline (domestic format)
* `61412345678` - International mobile (without + prefix)
* `+61312345678` - International landline (with + prefix)

**Invalid Examples:**

* `0123456789` - Starts with 1 (invalid area code)
* `04123456789` - Too many digits
* `04-1234-5678` - Contains formatting characters

### String Length Requirements

* **Street Number**: 1-12 characters
* **Street Name**: 1-100 characters
* **Suburb**: 1-100 characters
* **Postcode**: Exactly 4 digits (e.g., "3000", "2000")

### Medicare IRN

* Must contain only numeric digits
* Leading/trailing whitespace is automatically trimmed


## OpenAPI

````yaml PUT /v1/organizations/{organization_id}/users/{user_id}/patients/{patient_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}/patients/{patient_id}:
    put:
      description: Updates an existing patient in 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
        - name: patient_id
          in: path
          required: true
          description: Patient ID
          schema:
            type: string
            format: uuid
      requestBody:
        description: Patient data to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePatient'
        required: true
      responses:
        '200':
          description: Patient updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientUpdateResponse'
              example:
                success: true
                statusCode: 200
                message: Patient updated successfully
                data:
                  patient_id: pat_abc123def456
                  family_name: Smith
                  given_name: Jane
                  date_of_birth: '1985-03-15'
                  sex: F
                  phone: '0412345678'
                  email: jane.smith@example.com
                timestamp: '2024-01-15T10:30:00.000Z'
                requestId: req_1705312200000_abc123
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                statusCode: 401
                error:
                  type: https://parchment.health/errors/authentication-required
                  title: Unauthorized
                  detail: Valid authentication token is required
                timestamp: '2024-01-15T10:30:00.000Z'
                requestId: req_1705312200000_def456
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                statusCode: 403
                error:
                  type: https://parchment.health/errors/insufficient-scope
                  title: Insufficient permissions
                  detail: This operation requires the 'update:patient' scope
                timestamp: '2024-01-15T10:30:00.000Z'
                requestId: req_1705312200000_ghi789
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                statusCode: 422
                error:
                  type: https://parchment.health/errors/validation-error
                  title: Validation failed
                  detail: There were some problems with your input.
                  validation:
                    - field: phone
                      message: >-
                        Phone number must be a valid Australian number (e.g.,
                        0412345678, +61412345678)
                      code: VALIDATION_ERROR
                    - field: dva_file_number
                      message: >-
                        DVA card color is provided but DVA file number is
                        missing
                      code: VALIDATION_ERROR
                timestamp: '2024-01-15T10:30:00.000Z'
                requestId: req_1705312200000_jkl012
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                statusCode: 500
                error:
                  type: https://parchment.health/errors/internal-error
                  title: Internal server error
                  detail: Failed to update patient
                timestamp: '2024-01-15T10:30:00.000Z'
                requestId: req_1705312200000_mno345
components:
  schemas:
    UpdatePatient:
      type: object
      description: Patient update request - all fields are optional
      properties:
        family_name:
          type: string
          description: Patient's family/last name
        given_name:
          type: string
          description: Patient's given/first name
        date_of_birth:
          type: string
          format: date
          description: Date of birth in YYYY-MM-DD format
          example: '1985-03-15'
        sex:
          type: string
          enum:
            - M
            - F
            - I
            - 'N'
          description: 'Sex: M (Male), F (Female), I (Indeterminate), N (Not stated)'
        title:
          type: string
          description: Patient's title (Mr, Mrs, Ms, etc.)
        phone:
          type: string
          description: Australian phone number
          example: '0412345678'
        email:
          type: string
          format: email
          description: Email address
        ctg_eligible:
          type: boolean
          description: Closing the Gap eligibility
        indigenous_type:
          type: string
          enum:
            - Aboriginal
            - Torres Strait Islander
            - Both
            - Neither
            - Prefer not to say
          description: Indigenous status
        concession_pension_number:
          type: string
          description: Concession/pension card number
        entitlement_number:
          type: string
          description: Entitlement number
        ihi_number:
          type: string
          nullable: true
          pattern: ^\d{16}$
          description: >-
            16-digit Individual Healthcare Identifier (IHI). Must be exactly 16
            numeric digits.
        racf_id:
          type: string
          description: Residential Aged Care Facility ID
        is_inpatient:
          type: boolean
          description: Whether patient is an inpatient
        medicare_card_number:
          type: string
          nullable: true
          description: Medicare card number
        medicare_irn:
          type: string
          nullable: true
          description: Medicare IRN (numeric only)
        medicare_valid_to:
          type: string
          format: date
          nullable: true
          description: Medicare expiry date in YYYY-MM-DD format
        dva_file_number:
          type: string
          nullable: true
          description: DVA file number
        dva_card_color:
          type: string
          enum:
            - W
            - O
            - G
          nullable: true
          description: 'DVA card color: W (White), O (Orange), G (Gold)'
        australian_address:
          type: object
          description: Australian address
          properties:
            street_number:
              type: string
              maxLength: 12
              description: Street number
            street_name:
              type: string
              maxLength: 100
              description: Street name
            suburb:
              type: string
              maxLength: 100
              description: Suburb name
            state:
              type: string
              enum:
                - VIC
                - NSW
                - QLD
                - WA
                - SA
                - TAS
                - ACT
                - NT
              description: Australian state code
            postcode:
              type: string
              minLength: 4
              maxLength: 4
              description: 4-digit Australian postcode
          required:
            - street_number
            - street_name
            - suburb
            - state
            - postcode
    PatientUpdateResponse:
      allOf:
        - $ref: '#/components/schemas/ExternalApiResponse'
        - type: object
          properties:
            statusCode:
              example: 200
            message:
              example: Patient updated successfully
            data:
              type: object
              description: Updated patient data
    Error:
      $ref: '#/components/schemas/ExternalApiErrorResponse'
    ExternalApiResponse:
      type: object
      required:
        - success
        - statusCode
        - message
        - data
        - timestamp
        - requestId
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
          example: true
        statusCode:
          type: integer
          description: HTTP status code
          example: 200
        message:
          type: string
          description: Human-readable success message
          example: Success
        code:
          type: string
          description: Machine-readable operation code
          example: SUCCESS
        data:
          type: object
          description: Response payload data
        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_abc123
        pagination:
          type: object
          description: Pagination information for list operations
          properties:
            count:
              type: integer
              description: Number of items in current response
            hasNext:
              type: boolean
              description: Whether more items are available
            limit:
              type: integer
              description: Maximum items per page
            offset:
              type: integer
              description: Starting position of current page
            lastKey:
              type: string
              nullable: true
              description: >-
                Opaque cursor for fetching the next page. Use this value as the
                lastKey query parameter for the next request. If null, no more
                pages are available
    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

````