> ## 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. # Create patient > Creates a new patient in Parchment ## Response Examples ### Success Response (201 Created) ```json theme={null} { "success": true, "statusCode": 201, "message": "Patient created successfully", "data": { "external_patient_id": "CLINIKO#12345", "parchment_patient_id": "pat_abc123def456", "url": "https://app.parchment.health/dashboard/patients/pat_abc123def456" }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_abc123" } ``` ### Conflict Detected (202 Accepted) ```json theme={null} { "success": true, "statusCode": 202, "message": "Patient creation accepted - conflicts found", "data": { "external_patient_id": "CLINIKO#12345", "parchment_patient_id": "pat_existing789", "url": "https://app.parchment.health/dashboard/patients/pat_existing789" }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_def456" } ``` ### 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": "family_name", "message": "Family name cannot be empty", "code": "VALIDATION_ERROR" }, { "field": "given_name", "message": "Given name cannot be empty", "code": "VALIDATION_ERROR" }, { "field": "phone", "message": "Phone number must be a valid Australian number (e.g., 0412345678, +61412345678)", "code": "INVALID_FORMAT" }, { "field": "postcode", "message": "Postcode must be 4 digits", "code": "INVALID_FORMAT" } ] }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_ghi789" } ``` ### Partner Patient ID Conflict (409 Conflict) ```json theme={null} { "success": false, "statusCode": 409, "error": { "type": "https://parchment.health/errors/partner-patient-id-conflict", "title": "Partner patient ID conflict", "detail": "Partner patient ID 'CLINIKO#12345' is already in use by another patient. Please use a unique identifier." }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_jkl012" } ``` ### 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_mno345" } ``` ### 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 'CREATE_PATIENT' scope" }, "timestamp": "2024-01-15T10:30:00.000Z", "requestId": "req_1705312200000_pqr678" } ``` ## Response Fields ### Success Response Data | Field | Type | Description | | ---------------------- | ------ | --------------------------------------------------------- | | `external_patient_id` | string | Your system's patient identifier (as provided in request) | | `parchment_patient_id` | string | Parchment's unique patient identifier | | `url` | string | Direct link to patient in Parchment portal | ### 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 | | ----- | --------------------- | -------------------------------------------------------- | | `201` | Created | Patient successfully created | | `202` | Accepted | Patient creation accepted (demographic conflicts found) | | `400` | Bad Request | Invalid request format or missing required fields | | `401` | Unauthorized | Authentication required or token invalid | | `403` | Forbidden | Insufficient permissions (missing CREATE\_PATIENT scope) | | `409` | Conflict | Partner patient ID already exists | | `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` - Melbourne landline (domestic format) * `0212345678` - Sydney landline (domestic format) * `0712345678` - Brisbane landline (domestic format) * `0812345678` - Adelaide 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 * `041234567` - Too few digits * `04-1234-5678` - Contains formatting characters * `+1234567890` - Non-Australian number ### IHI Number The `ihi_number` field is an optional 16-digit Individual Healthcare Identifier. * If provided, it must be exactly 16 numeric digits (e.g., `"8003608500035100"`). * If omitted, Parchment will attempt to fetch the IHI automatically from the HI Service using the patient's demographics and Medicare/DVA details. ### String Length Requirements * **Family Name**: 1-255 characters, cannot be empty * **Given Name**: 1-255 characters, cannot be empty * **Partner Patient ID**: 1-150 characters, must be unique * **Street Number**: 1-12 characters * **Street Name**: 1-100 characters * **Suburb**: 1-100 characters * **Postcode**: Exactly 4 digits (e.g., "3000", "2000") ## Integration Notes 1. **Store Request ID**: Always log the `requestId` for debugging support requests 2. **Handle 202 Status**: A 202 response indicates demographic conflicts were found but a matching patient was returned 3. **Validation Errors**: Use the `error.validation` array to display field-specific error messages 4. **Partner Patient ID**: Must be unique across your organization; use the format returned in `external_patient_id` 5. **URL Access**: The returned `url` provides direct access to the patient in the Parchment portal 6. **Phone Validation**: Phone numbers must follow Australian format - see validation requirements above 7. **IHI Lookup**: Omit `ihi_number` to have Parchment resolve it via the HI Service; provide it explicitly only when you already hold a verified 16-digit IHI ## OpenAPI ````yaml POST /v1/organizations/{organization_id}/users/{user_id}/patients 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: post: description: Creates a new 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 requestBody: description: Patient data to add to Parchment content: application/json: schema: $ref: '#/components/schemas/NewPatient' required: true responses: '201': description: Patient created successfully content: application/json: schema: $ref: '#/components/schemas/PatientResponse' example: success: true statusCode: 201 message: Patient created successfully data: external_patient_id: PARTNER#12345 parchment_patient_id: pat_abc123def456 url: >- https://app.parchment.health/dashboard/patients/pat_abc123def456 timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 '202': description: Patient creation accepted - conflicts found content: application/json: schema: $ref: '#/components/schemas/PatientResponse' example: success: true statusCode: 202 message: Patient creation accepted - conflicts found data: external_patient_id: PARTNER#12345 parchment_patient_id: pat_existing789 url: >- https://app.parchment.health/dashboard/patients/pat_existing789 timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_def456 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false statusCode: 400 error: type: https://parchment.health/errors/invalid-request title: Bad request detail: The request could not be processed due to invalid data. timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_mno345 '409': description: Partner patient ID conflict content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false statusCode: 409 error: type: https://parchment.health/errors/partner-patient-id-conflict title: Partner patient ID conflict detail: >- Partner patient ID 'PARTNER#12345' is already in use by another patient. Please use a unique identifier. 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: family_name message: Family name is required code: VALIDATION_ERROR - field: date_of_birth message: Invalid date format. Use YYYY-MM-DD code: INVALID_FORMAT timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_jkl012 components: schemas: NewPatient: type: object description: Patient information to be created required: - family_name - given_name - date_of_birth - sex - partner_patient_id properties: dva_file_number: type: string description: DVA file number ihi_number: type: string description: >- 16-digit Individual Healthcare Identifier (IHI). If omitted, Parchment will attempt to fetch it from the HI Service. medicare_card_number: type: string description: Medicare card number medicare_irn: type: string description: Medicare IRN given_name: type: string description: Patient's given name family_name: type: string description: Patient's family name date_of_birth: type: string format: date description: Patient's date of birth in YYYY-MM-DD format sex: $ref: '#/components/schemas/Sex' email: type: string format: email description: Patient's email address (optional) phone: type: string description: >- Patient's Australian phone number (optional). Must be a valid Australian number with digits only. Supports mobile (04xxxxxxxx) and landline (0[2378]xxxxxxxx) formats. International format with +61 or 61 prefix is also accepted. australian_address: $ref: '#/components/schemas/australian_street_address' medicare_valid_to: type: string format: date description: Medicare card expiry date concession_pension_number: type: string description: Concession or pension number entitlement_number: type: string description: Entitlement number dva_card_color: $ref: '#/components/schemas/DVA_COLOR' racf_id: type: string description: RACF identifier ctg_eligible: type: boolean description: Closing the Gap eligibility indigenous_type: $ref: '#/components/schemas/IndigenousType' partner_patient_id: type: string description: Partner's unique identifier for the patient partner_id: type: string description: Partner's unique identifier for the organization PatientResponse: allOf: - $ref: '#/components/schemas/ExternalApiResponse' - type: object properties: statusCode: example: 201 message: example: Patient created successfully data: $ref: '#/components/schemas/PatientData' Error: $ref: '#/components/schemas/ExternalApiErrorResponse' Sex: type: string enum: - M - F - 'N' - I description: Patient's sex australian_street_address: type: object required: - street_number - street_name - suburb - state - postcode properties: street_number: type: string description: Street number street_name: type: string description: Street name suburb: type: string description: Suburb state: $ref: '#/components/schemas/AU_STATE' postcode: type: string description: Australian postcode (4 digits) DVA_COLOR: type: string enum: - gold - white - orange description: DVA card color IndigenousType: type: string enum: - aboriginal - torres_strait_islander - both - neither - not_stated description: Patient's indigenous status 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 PatientData: type: object description: Patient creation response data required: - external_patient_id - parchment_patient_id - url properties: external_patient_id: type: string description: Partner's unique identifier for the patient example: PARTNER#12345 parchment_patient_id: type: string description: Parchment's unique identifier for the patient example: pat_abc123def456 url: type: string format: uri description: URL to access the patient in Parchment portal example: https://app.parchment.health/dashboard/patients/pat_abc123def456 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' AU_STATE: type: string enum: - NSW - VIC - QLD - WA - SA - TAS - ACT - NT description: Australian state or territory securitySchemes: bearerAuth: type: http scheme: bearer ````