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

# Create Patient

> Creates a new patient in your organization

## Request Body

<ParamField body="firstName" type="string" required>
  Patient's first name. Min 1 character, max 255 characters.
</ParamField>

<ParamField body="lastName" type="string" required>
  Patient's last name. Min 1 character, max 255 characters.
</ParamField>

<ParamField body="phoneNumber" type="string" required>
  Phone number in E.164 format. Must start with `+` followed by country code and
  number. **Examples:** - Australia: `+61412345678` - US: `+14155551234` - UK:
  `+447700900123`
</ParamField>

<ParamField body="dateOfBirth" type="string" required>
  Date of birth in ISO 8601 format (`YYYY-MM-DD`). **Example:** `1990-01-15`
</ParamField>

<ParamField body="email" type="string">
  Valid email address for the patient.
</ParamField>

<ParamField body="addressLine1" type="string">
  Street address line 1. Max 255 characters.
</ParamField>

<ParamField body="addressLine2" type="string">
  Street address line 2 (apartment, suite, etc.). Max 255 characters.
</ParamField>

<ParamField body="suburb" type="string">
  Suburb or city. Max 100 characters.
</ParamField>

<ParamField body="state" type="string">
  State or province. Max 50 characters.
</ParamField>

<ParamField body="postcode" type="string">
  Postal or ZIP code. Max 20 characters.
</ParamField>

<ParamField body="country" type="string">
  Country code. Currently only `AU` (Australia) is supported.
</ParamField>

## Response

<ResponseField name="data" type="object">
  The created patient object.

  <Expandable title="Patient object properties">
    <ResponseField name="id" type="string">
      Unique patient identifier (UUID).
    </ResponseField>

    <ResponseField name="firstName" type="string">
      Patient's first name.
    </ResponseField>

    <ResponseField name="lastName" type="string">
      Patient's last name.
    </ResponseField>

    <ResponseField name="phoneNumber" type="string">
      Phone number in E.164 format.
    </ResponseField>

    <ResponseField name="email" type="string">
      Patient's email address.
    </ResponseField>

    <ResponseField name="dateOfBirth" type="string | null">
      Date of birth (YYYY-MM-DD) or null if not provided.
    </ResponseField>

    <ResponseField name="addressLine1" type="string | null">
      Street address line 1.
    </ResponseField>

    <ResponseField name="addressLine2" type="string | null">
      Street address line 2.
    </ResponseField>

    <ResponseField name="suburb" type="string | null">
      Suburb or city.
    </ResponseField>

    <ResponseField name="state" type="string | null">
      State or province.
    </ResponseField>

    <ResponseField name="postcode" type="string | null">
      Postal or ZIP code.
    </ResponseField>

    <ResponseField name="country" type="string | null">
      Country code.
    </ResponseField>

    <ResponseField name="organisationId" type="string">
      Your organization ID (UUID).
    </ResponseField>

    <ResponseField name="isIdentified" type="boolean">
      Whether the patient is fully identified. Always `true` for API-created
      patients.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the patient was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp when the patient was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Additional metadata (currently empty).
</ResponseField>

## Examples

<Tabs>
  <Tab title="Development">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      const response = await fetch(
        "https://api.demo.operahealth.ai/api/v1/patients",
        {
          method: "POST",
          headers: {
            Authorization: "Bearer opera_demo_your_api_key_here",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            firstName: "John",
            lastName: "Doe",
            phoneNumber: "+61412345678",
            email: "john.doe@example.com",
            dateOfBirth: "1990-01-15",
            addressLine1: "123 Main St",
            suburb: "Melbourne",
            state: "VIC",
            postcode: "3000",
            country: "AU",
          }),
        }
      );

      if (!response.ok) {
        const error = await response.json();
        console.error("Error:", error);
        throw new Error(error.detail);
      }

      const { data } = await response.json();
      console.log("Patient created:", data);
      ```

      ```python Python theme={null}
      import requests

      url = "https://api.demo.operahealth.ai/api/v1/patients"
      headers = {
          "Authorization": "Bearer opera_demo_your_api_key_here",
          "Content-Type": "application/json"
      }
      payload = {
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+61412345678",
          "email": "john.doe@example.com",
          "dateOfBirth": "1990-01-15",
          "addressLine1": "123 Main St",
          "suburb": "Melbourne",
          "state": "VIC",
          "postcode": "3000",
          "country": "AU"
      }

      response = requests.post(url, json=payload, headers=headers)

      if response.status_code == 201:
          patient = response.json()["data"]
          print(f"Patient created: {patient['id']}")
      else:
          error = response.json()
          print(f"Error: {error['detail']}")
      ```

      ```bash cURL theme={null}
      curl -X POST https://api.demo.operahealth.ai/api/v1/patients \
        -H "Authorization: Bearer opera_demo_your_api_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+61412345678",
          "email": "john.doe@example.com",
          "dateOfBirth": "1990-01-15",
          "addressLine1": "123 Main St",
          "suburb": "Melbourne",
          "state": "VIC",
          "postcode": "3000",
          "country": "AU"
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Production">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      const response = await fetch(
        "https://api.prod.operahealth.ai/api/v1/patients",
        {
          method: "POST",
          headers: {
            Authorization: "Bearer opera_live_your_api_key_here",
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            firstName: "John",
            lastName: "Doe",
            phoneNumber: "+61412345678",
            email: "john.doe@example.com",
            dateOfBirth: "1990-01-15",
            addressLine1: "123 Main St",
            suburb: "Melbourne",
            state: "VIC",
            postcode: "3000",
            country: "AU",
          }),
        }
      );

      if (!response.ok) {
        const error = await response.json();
        console.error("Error:", error);
        throw new Error(error.detail);
      }

      const { data } = await response.json();
      console.log("Patient created:", data);
      ```

      ```python Python theme={null}
      import requests

      url = "https://api.prod.operahealth.ai/api/v1/patients"
      headers = {
          "Authorization": "Bearer opera_live_your_api_key_here",
          "Content-Type": "application/json"
      }
      payload = {
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+61412345678",
          "email": "john.doe@example.com",
          "dateOfBirth": "1990-01-15",
          "addressLine1": "123 Main St",
          "suburb": "Melbourne",
          "state": "VIC",
          "postcode": "3000",
          "country": "AU"
      }

      response = requests.post(url, json=payload, headers=headers)

      if response.status_code == 201:
          patient = response.json()["data"]
          print(f"Patient created: {patient['id']}")
      else:
          error = response.json()
          print(f"Error: {error['detail']}")
      ```

      ```bash cURL theme={null}
      curl -X POST https://api.prod.operahealth.ai/api/v1/patients \
        -H "Authorization: Bearer opera_live_your_api_key_here" \
        -H "Content-Type: application/json" \
        -d '{
          "firstName": "John",
          "lastName": "Doe",
          "phoneNumber": "+61412345678",
          "email": "john.doe@example.com",
          "dateOfBirth": "1990-01-15",
          "addressLine1": "123 Main St",
          "suburb": "Melbourne",
          "state": "VIC",
          "postcode": "3000",
          "country": "AU"
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<RequestExample>
  ```json Request Body theme={null}
  {
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+61412345678",
    "email": "john.doe@example.com",
    "dateOfBirth": "1990-01-15",
    "addressLine1": "123 Main St",
    "addressLine2": "Apt 4B",
    "suburb": "Melbourne",
    "state": "VIC",
    "postcode": "3000",
    "country": "AU"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "data": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "+61412345678",
      "email": "john.doe@example.com",
      "dateOfBirth": "1990-01-15",
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 4B",
      "suburb": "Melbourne",
      "state": "VIC",
      "postcode": "3000",
      "country": "AU",
      "organisationId": "org-uuid-here",
      "isIdentified": true,
      "createdAt": "2025-12-03T10:30:00.000Z",
      "updatedAt": "2025-12-03T10:30:00.000Z"
    },
    "meta": {}
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "type": "about:blank",
    "title": "Unauthorized",
    "status": 401,
    "detail": "Missing or invalid API key",
    "instance": null
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "type": "about:blank",
    "title": "Validation Error",
    "status": 422,
    "detail": "Validation failed",
    "instance": null,
    "errors": [
      {
        "path": ["phoneNumber"],
        "message": "Phone number must be in E.164 format (e.g., +1234567890)"
      }
    ]
  }
  ```
</ResponseExample>


## OpenAPI

````yaml api-reference/endpoint/api-reference/openapi.json post /patients
openapi: 3.1.0
info:
  title: Operahealth API
  description: >-
    REST API for third-party integrations to programmatically manage patient
    data in Operahealth.
  version: 1.0.0
servers:
  - url: https://api.demo.operahealth.ai/api/v1
    description: Development server
  - url: https://api.prod.operahealth.ai/api/v1
    description: Production server
security:
  - bearerAuth: []
paths:
  /patients:
    post:
      tags:
        - Patients
      summary: Create Patient
      description: Creates a new patient in your organization.
      operationId: createPatient
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePatientRequest'
            example:
              firstName: John
              lastName: Doe
              phoneNumber: '+61412345678'
              email: john.doe@example.com
              dateOfBirth: '1990-01-15'
              addressLine1: 123 Main St
              addressLine2: Apt 4B
              suburb: Melbourne
              state: VIC
              postcode: '3000'
              country: AU
      responses:
        '201':
          description: Patient created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientResponse'
              example:
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  firstName: John
                  lastName: Doe
                  phoneNumber: '+61412345678'
                  email: john.doe@example.com
                  dateOfBirth: '1990-01-15'
                  addressLine1: 123 Main St
                  addressLine2: Apt 4B
                  suburb: Melbourne
                  state: VIC
                  postcode: '3000'
                  country: AU
                  organisationId: org-uuid-here
                  isIdentified: true
                  createdAt: '2025-12-03T10:30:00.000Z'
                  updatedAt: '2025-12-03T10:30:00.000Z'
                meta: {}
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: Unauthorized
                status: 401
                detail: Missing or invalid API key
                instance: null
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              example:
                type: about:blank
                title: Validation Error
                status: 422
                detail: Validation failed
                instance: null
                errors:
                  - path:
                      - phoneNumber
                    message: Phone number must be in E.164 format (e.g., +1234567890)
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                type: about:blank
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred
                instance: null
components:
  schemas:
    CreatePatientRequest:
      type: object
      required:
        - firstName
        - lastName
        - phoneNumber
        - dateOfBirth
      properties:
        firstName:
          type: string
          minLength: 1
          maxLength: 255
          description: Patient's first name
        lastName:
          type: string
          minLength: 1
          maxLength: 255
          description: Patient's last name
        phoneNumber:
          type: string
          description: Phone number in E.164 format (e.g., +61412345678)
          pattern: ^\+[1-9]\d{1,14}$
        email:
          type: string
          format: email
          description: Patient's email address
          nullable: true
        dateOfBirth:
          type: string
          format: date
          description: Date of birth in ISO 8601 format (YYYY-MM-DD)
        addressLine1:
          type: string
          maxLength: 255
          description: Street address line 1
          nullable: true
        addressLine2:
          type: string
          maxLength: 255
          description: Street address line 2 (apartment, suite, etc.)
          nullable: true
        suburb:
          type: string
          maxLength: 100
          description: Suburb or city
          nullable: true
        state:
          type: string
          maxLength: 50
          description: State or province
          nullable: true
        postcode:
          type: string
          maxLength: 20
          description: Postal or ZIP code
          nullable: true
        country:
          type: string
          enum:
            - AU
          description: Country code (only Australia supported)
          nullable: true
    PatientResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Patient'
        meta:
          type: object
          description: Additional metadata
    Error:
      type: object
      properties:
        type:
          type: string
          description: A URI reference identifying the problem type
        title:
          type: string
          description: A short, human-readable summary
        status:
          type: integer
          description: The HTTP status code
        detail:
          type: string
          description: A human-readable explanation
        instance:
          type: string
          nullable: true
          description: A URI reference identifying the specific occurrence
    ValidationError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            errors:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: array
                    items:
                      type: string
                    description: Path to the field that failed validation
                  message:
                    type: string
                    description: Human-readable error message
    Patient:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique patient identifier
        firstName:
          type: string
          description: Patient's first name
        lastName:
          type: string
          description: Patient's last name
        phoneNumber:
          type: string
          description: Phone number in E.164 format
        email:
          type: string
          format: email
          description: Patient's email address
        dateOfBirth:
          type: string
          format: date
          nullable: true
          description: Date of birth (YYYY-MM-DD)
        addressLine1:
          type: string
          nullable: true
          description: Street address line 1
        addressLine2:
          type: string
          nullable: true
          description: Street address line 2
        suburb:
          type: string
          nullable: true
          description: Suburb or city
        state:
          type: string
          nullable: true
          description: State or province
        postcode:
          type: string
          nullable: true
          description: Postal or ZIP code
        country:
          type: string
          nullable: true
          description: Country code
        organisationId:
          type: string
          format: uuid
          description: Your organization ID
        isIdentified:
          type: boolean
          description: >-
            Whether patient is fully identified (always true for API-created
            patients)
        createdAt:
          type: string
          format: date-time
          description: Timestamp when patient was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when patient was last updated
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authentication using Bearer scheme. Get your API key from the
        Operahealth dashboard.

````