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

# Create a patient

> Creates a patient, as **Add patient** does in the app, and returns its `id` for creating visits. With `external_id`, a patient that already exists for that id is returned (200) instead of a duplicate. Scope `patients:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /patients
openapi: 3.1.0
info:
  title: RxNote API
  version: 1.0.0
  description: >-
    The RxNote app's patient → visit → note flow for your own software: create a
    patient, create a visit with a recording or a transcript, and get back the
    transcript and a structured clinical note.
servers:
  - url: https://rxnote.ai/api/v1
    description: Production
  - url: https://dev.rxnote.ai/api/v1
    description: Sandbox (test keys)
  - url: http://localhost:3000/api/v1
    description: Local development
security: []
paths:
  /patients:
    post:
      tags:
        - Patients
      summary: Create a patient
      description: >-
        Creates a patient, as **Add patient** does in the app, and returns its
        `id` for creating visits. With `external_id`, a patient that already
        exists for that id is returned (200) instead of a duplicate. Scope
        `patients:write`.
      operationId: createPatient
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePatientRequest'
      responses:
        '200':
          description: The patient that already had this `external_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '201':
          description: The new patient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid, revoked or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The key lacks the scope, or the API is not enabled for the account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The clinician is not a member of the account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate or concurrency limit reached; see `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKey: []
components:
  schemas:
    CreatePatientRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          example: Test Patient
        age:
          type: integer
          minimum: 0
          maximum: 130
          example: 42
        sex:
          type: string
          enum:
            - male
            - female
            - other
        date_of_birth:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: YYYY-MM-DD
          example: '1984-03-02'
        phone:
          type: string
          maxLength: 30
          example: '+919800000000'
        email:
          type: string
          maxLength: 255
          format: email
        medical_record_number:
          type: string
          maxLength: 100
          description: Your MRN / UHID, searchable later.
          example: MRN-1001
        external_id:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            Your system's id for this patient. Creating a patient with an
            external_id that already exists returns that patient instead of a
            duplicate.
          example: P-1001
        clinician_email:
          type: string
          maxLength: 255
          format: email
          description: >-
            Required with an organization key: the RxNote member acting. With a
            personal key, omit it or send the owner's own email.
          example: doctor@clinic.example
      required:
        - name
    Patient:
      type: object
      properties:
        id:
          type: integer
          example: 4821
        name:
          type: string
        age:
          type:
            - integer
            - 'null'
        sex:
          type:
            - string
            - 'null'
        date_of_birth:
          type:
            - string
            - 'null'
        phone:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        medical_record_number:
          type:
            - string
            - 'null'
        external_id:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
      required:
        - id
        - name
        - age
        - sex
        - date_of_birth
        - phone
        - email
        - medical_record_number
        - external_id
        - created_at
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_FAILED
            message:
              type: string
            request_id:
              type: string
              example: req_Q2w9Lx7Hc4Vb8Np1Zs3Kt6
          required:
            - code
            - message
            - request_id
      required:
        - error
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Your API key, created in RxNote under Settings → API: `Authorization:
        Bearer rxn_live_…`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.