> ## 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 user > Creates a new user in Parchment ## Response Examples ### Success Response (201 Created) ```json theme={null} { "success": true, "statusCode": 201, "message": "User created successfully", "code": "USER_CREATED", "data": { "user_id": "0b4c1a49-fea8-4922-a3da-2ca8jf8af9bd" }, "timestamp": "2025-09-22T20:31:54.558Z", "requestId": "1-68d1b225-2a98752c7b2da3fa489267fc" } ``` ### Partial Success - User Already Exists (201 Created) ```json theme={null} { "success": false, "statusCode": 409, "code": "USER_ALREADY_EXISTS", "error": { "type": "https://parchment.health/errors/resource-conflict", "title": "Resource conflict", "detail": "User with this email already exists" }, "timestamp": "2025-09-22T20:46:51.702Z", "requestId": "1-68d1b5b6-31fbc67e15cff9b13268e6f0" } ``` ### Partial Success = Provider Already Exists (201 Created) ```json theme={null} { "success": true, "statusCode": 201, "message": "User created but provider already exists", "code": "USER_CREATED_PROVIDER_ALREADY_EXISTS", "data": { "user_id": "5b048ac0-b078-4955-88d5-1c4bc5147d3b", "warning": "User created successfully but provider creation failed" }, "timestamp": "2025-09-22T21:15:45.541Z", "requestId": "1-68d1bc7a-2249a4da021230520c2dc288" } ``` ### Partial Success - Provider Creation Failed (201 Created) ```json theme={null} { "success": true, "statusCode": 201, "message": "User created but provider not found", "code": "USER_CREATED_PROVIDER_NOT_FOUND", "data": { "user_id": "faa41171-235e-4822-b524-9f8bb07ebd3d", "warning": "User created successfully but provider search failed" }, "timestamp": "2025-09-22T20:48:47.878Z", "requestId": "1-68d1b61a-156915754ad812fd58a24d90" } ``` ### Validation Error (422 Unprocessable Entity) ```json theme={null} { "success": false, "statusCode": 422, "code": "VALIDATION_ERROR", "error": { "type": "https://parchment.health/errors/validation-error", "title": "Validation failed", "detail": "There were some problems with your input.", "validation": [ { "field": "hpii_number", "message": "HPII Number is required and must be valid when access_roles contains \"provider\" or \"rx_queue_manager\"", "code": "VALIDATION_ERROR" } ] }, "timestamp": "2025-09-22T20:47:35.790Z", "requestId": "1-68d1b5e7-0a243a3a24ba148126eff847" } ``` ### Unauthorized (401) ```json theme={null} { "success": false, "statusCode": 401, "code": "UNAUTHORIZED", "error": { "type": "https://parchment.health/errors/authentication-required", "title": "Unauthorized", "detail": "invalid signature" }, "timestamp": "2025-09-22T20:50:36.942Z", "requestId": "1-68d1b69c-3599f32a653cd17e49a79a07" } ``` ## Response Fields ### Success Response Data | Field | Type | Description | | ------------------- | ------ | ------------------------------------------------------ | | `external_user_id` | string | Your system's user identifier (as provided in request) | | `parchment_user_id` | string | Parchment's unique user identifier | | `url` | string | Direct link to user 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 | User successfully created | | `202` | Accepted | User 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\_USER scope) | | `409` | Conflict | Partner user ID already exists | | `422` | Unprocessable Entity | Request validation failed | | `500` | Internal Server Error | Unexpected server error | ## Field Validation Requirements ### Required Fields | Field | Type | Required When | Description | | ------------------- | ------ | --------------------------------------------------------------- | ----------------------------------------- | | `given_name` | string | Always | User's given name | | `family_name` | string | Always | User's family name | | `email` | string | Always | User's email address | | `date_of_birth` | string | When `access_roles` includes "provider" or "rx\_queue\_manager" | Date of birth in YYYY-MM-DD format | | `sex` | string | When `access_roles` includes "provider" or "rx\_queue\_manager" | Sex (M/F/I/N) | | `hpii_number` | string | When `access_roles` includes "provider" or "rx\_queue\_manager" | Healthcare Provider Individual Identifier | | `prescriber_type` | string | When `access_roles` includes "provider" | Prescriber type (M/N/D/P/T) | | `prescriber_number` | string | When role is "provider" and `prescriber_type` is not "T" | Prescriber number | | `qualifications` | string | When `access_roles` includes "provider" or "rx\_queue\_manager" | Professional qualifications | ### Optional Fields | Field | Type | Description | | -------------------------- | ------ | ------------------------- | | `access_roles` | array | User roles | | `title` | string | Professional title | | `provider_number` | string | Medicare provider number | | `ahpra_number` | string | AHPRA registration number | | `hospital_provider_number` | string | Hospital provider number | | `phone` | string | Clinic's Number | ### 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 ### String Length Requirements * **Family Name**: 1-255 characters, cannot be empty * **Given Name**: 1-255 characters, cannot be empty * **HPII Number**: 16 digits exactly * **Prescriber Number**: 1-10 characters * **AHPRA Number**: 1-15 characters * **Provider Number**: 1-15 characters * **Qualifications**: 1-255 characters ### Sex * `M` (Male) * `F` (Female) * `I` (Indeterminate) * `N` (Not-stated) ### Access Roles Valid values for `access_roles` array: * `admin` (Administrative access) * `provider` (Healthcare provider access) * `receptionist` (Can read patient demographics) * `rx_reader` (Can reissue scripts) * `rx_queue_manager` (Can manage the prescription queue on behalf of prescribers) When the `provider` or `rx_queue_manager` role is included, additional fields become required: * `provider`: `date_of_birth`, `sex`, `hpii_number`, `qualifications`, and `prescriber_type` (plus `prescriber_number` unless `prescriber_type` is "T") * `rx_queue_manager`: `date_of_birth`, `sex`, `hpii_number`, and `qualifications` (`prescriber_type` and `prescriber_number` are **not** required) ### Prescriber Types Valid values for `prescriber_type` when role is "provider": * `M` (Medical Practitioner) * `E` (Eye/Optometrist) * `U` (Nurse) * `F` (Midwife) * `D` (Dentist) * `V` (Vetinarian) * `T` (Podiatrist) * `C` (Pharmacist) ## 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 user was returned 3. **Validation Errors**: Use the `error.validation` array to display field-specific error messages 4. **Partner User ID**: Must be unique across your organization; use the format returned in `external_user_id` 5. **URL Access**: The returned `url` provides direct access to the user in the Parchment portal 6. **Provider Role Requirements**: When creating users with the `provider` or `rx_queue_manager` role, ensure all required identity fields are included (see Access Roles above) — these roles create a provider record attributed to a verified healthcare individual 7. **Phone Validation**: Phone numbers must follow Australian format - see validation requirements above ## Example Request ```json theme={null} { "given_name": "Darlene", "family_name": "Cameron", "date_of_birth": "1969-10-02", "sex": "F", "email": "darlene.cameron@example.com", "phone": "0412345678", "access_roles": [ "admin", "provider" ], "hpii_number": "8003614900029560", "prescriber_type": "M", "prescriber_number": "1234567", "qualifications": "LLB", "title": "Dr", "provider_number": "123456789", "ahpra_number": "1234567896321", "hospital_provider_number": "H123456", "partner_user_id": "CLINIKO#USER_12345" } ``` ## OpenAPI ````yaml POST /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: post: description: Creates a new user 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 requestBody: description: User data to add to Parchment content: application/json: schema: $ref: '#/components/schemas/NewUser' required: true responses: '201': description: User created successfully content: application/json: schema: $ref: '#/components/schemas/UserResponse' example: success: true statusCode: 201 message: User created successfully data: external_user_id: PARTNER#USER_12345 parchment_user_id: usr_abc123def456 url: >- https://app.parchment.health/dashboard/users/usr_abc123def456 timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_abc123 '202': description: User creation accepted - conflicts found content: application/json: schema: $ref: '#/components/schemas/UserResponse' example: success: true statusCode: 202 message: User creation accepted - conflicts found data: external_user_id: PARTNER#USER_12345 parchment_user_id: usr_existing789 url: https://app.parchment.health/dashboard/users/usr_existing789 timestamp: '2024-01-15T10:30:00.000Z' requestId: req_1705312200000_def456 '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' '409': description: Conflict - Partner user ID already exists content: application/json: schema: $ref: '#/components/schemas/ExternalApiErrorResponse' '422': description: Unprocessable Entity - Validation failed content: application/json: schema: $ref: f67a243e-0187-4dd3-9099-c206f2c1e229 '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ExternalApiErrorResponse' components: schemas: NewUser: type: object description: User information to be created required: - family_name - given_name - email - partner_user_id properties: given_name: type: string description: User's given name example: Darlene family_name: type: string description: User's family name example: Cameron date_of_birth: type: string format: date description: >- User's date of birth in YYYY-MM-DD format (required if role includes 'provider' or 'rx_queue_manager') example: '1969-10-02' sex: type: string description: >- User's sex (required if role includes 'provider' or 'rx_queue_manager') enum: - M - F - I - O example: F email: type: string format: email description: User's email address example: darlene.cameron@example.com phone: type: string description: >- User's Australian phone number. 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. example: '0412345678' access_roles: type: array description: >- List of access roles for the user. Roles 'provider' and 'rx_queue_manager' require additional identity fields (date_of_birth, sex, hpii_number, qualifications); 'provider' additionally requires prescriber_type (and prescriber_number unless prescriber_type is 'T'). items: type: string enum: - admin - provider - receptionist - rx_reader - rx_queue_manager example: - admin - provider hpii_number: type: string description: >- Healthcare Provider Individual Identifier (required if role includes 'provider' or 'rx_queue_manager') example: '8003614900029560' prescriber_type: type: string description: Prescriber type (required if role includes 'provider') enum: - M - 'N' - D - P - T example: M prescriber_number: type: string description: >- Prescriber number (required if role includes 'provider' and prescriber_type is not 'T') example: '1234567' qualifications: type: string description: >- Professional qualifications (required if role includes 'provider' or 'rx_queue_manager') example: LLB title: type: string description: Professional title example: Dr provider_number: type: string description: Medicare provider number example: '123456789' ahpra_number: type: string description: AHPRA registration number example: '1234567896321' hospital_provider_number: type: string description: Hospital provider number example: H123456 partner_user_id: type: string description: Partner's unique identifier for the user example: CLINIKO#USER_12345 UserResponse: allOf: - $ref: '#/components/schemas/ExternalApiResponse' - type: object properties: statusCode: example: 201 message: example: User created successfully data: $ref: '#/components/schemas/UserData' 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' 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 UserData: type: object description: User creation response data required: - external_user_id - parchment_user_id - url properties: external_user_id: type: string description: Partner's unique identifier for the user example: PARTNER#USER_12345 parchment_user_id: type: string description: Parchment's unique identifier for the user example: usr_abc123def456 url: type: string description: Direct link to user in Parchment portal example: https://app.parchment.health/dashboard/users/usr_abc123def456 securitySchemes: bearerAuth: type: http scheme: bearer ````