Akute Appointments API

openapi: 3.0.1
info:
  title: Akute Health Customer API
  description: >-
    REST API for the Akute Health automation-first EHR platform. Exposes
    FHIR-aligned resources - patients, appointments, clinical notes
    (encounters), tasks, documents, medications and e-prescribing, lab orders,
    diagnostic reports and observations - plus webhook subscriptions for
    resource events. Authentication uses an API key passed in the X-API-Key
    header. Webhook deliveries are signed with HMAC-SHA256 in the
    x-akute-signature header.
  termsOfService: https://www.akutehealth.com/
  contact:
    name: Akute Health Support
    email: support@akutehealth.com
    url: https://developer.akutehealth.com/
  version: '1.0'
servers:
  - url: https://api.akutehealth.com/v1
    description: Production
  - url: https://api.staging.akutehealth.com/v1
    description: Staging
security:
  - APIKeyHeader: []
tags:
  - name: Patients
  - name: Appointments
  - name: Encounters
  - name: Tasks
  - name: Documents
  - name: Medications
  - name: Labs
  - name: Webhooks
paths:
  /patients:
    post:
      operationId: createPatient
      tags: [Patients]
      summary: Create a patient
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
    get:
      operationId: searchPatients
      tags: [Patients]
      summary: Search patients
      description: >-
        Search patients by demographics, contact details, or external_id.
        Returns a paginated list.
      parameters:
        - name: external_id
          in: query
          schema: { type: string }
        - name: first_name
          in: query
          schema: { type: string }
        - name: last_name
          in: query
          schema: { type: string }
        - name: middle_name
          in: query
          schema: { type: string }
        - name: date_of_birth
          in: query
          schema: { type: string, format: date }
        - name: sex
          in: query
          schema: { type: string, enum: [male, female, other, unknown] }
        - name: email
          in: query
          schema: { type: string, format: email }
        - name: primary_phone_number
          in: query
          schema: { type: string }
        - name: status
          in: query
          schema: { type: string, enum: [active, inactive] }
        - name: limit
          in: query
          schema: { type: integer, default: 100 }
        - name: offset
          in: query
          schema: { type: integer, default: 0 }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Patient'
  /patients/{patient_id}:
    get:
      operationId: getPatient
      tags: [Patients]
      summary: Get a patient by id
      parameters:
        - $ref: '#/components/parameters/PatientId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
    put:
      operationId: updatePatient
      tags: [Patients]
      summary: Update a patient
      parameters:
        - $ref: '#/components/parameters/PatientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientCreate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Patient'
  /patients/{patient_id}/external_ids:
    get:
      operationId: getPatientExternalIds
      tags: [Patients]
      summary: Get a patient's external ids
      parameters:
        - $ref: '#/components/parameters/PatientId'
      responses:
        '200':
          description: OK
  /appointments:
    post:
      operationId: createAppointment
      tags: [Appointments]
      summary: Create an appointment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Appointment'
      responses:
        '201':
          description: Created
    get:
      operationId: searchAppointments
      tags: [Appointments]
      summary: Search appointments
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: practitioner_user_id
          in: query
          schema: { type: string }
        - name: start_range
          in: query
          schema: { type: string }
        - name: end_range
          in: query
          schema: { type: string }
        - name: status
          in: query
          schema: { type: string, enum: [booked, fulfilled, cancelled, noshow] }
      responses:
        '200':
          description: OK
  /appointments/{appointment_id}:
    get:
      operationId: getAppointment
      tags: [Appointments]
      summary: Get an appointment by id
      parameters:
        - $ref: '#/components/parameters/AppointmentId'
      responses:
        '200':
          description: OK
    put:
      operationId: updateAppointment
      tags: [Appointments]
      summary: Update an appointment
      parameters:
        - $ref: '#/components/parameters/AppointmentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Appointment'
      responses:
        '200':
          description: OK
    delete:
      operationId: deleteAppointment
      tags: [Appointments]
      summary: Cancel/delete an appointment
      parameters:
        - $ref: '#/components/parameters/AppointmentId'
      responses:
        '200':
          description: OK
  /appointment_types:
    get:
      operationId: listAppointmentTypes
      tags: [Appointments]
      summary: List appointment types
      responses:
        '200':
          description: OK
  /availability:
    get:
      operationId: getAvailability
      tags: [Appointments]
      summary: Get practitioner availability
      parameters:
        - name: user_id
          in: query
          required: true
          schema: { type: string }
        - name: start_time
          in: query
          schema: { type: string, format: date-time }
        - name: end_time
          in: query
          schema: { type: string, format: date-time }
      responses:
        '200':
          description: OK
  /notes:
    post:
      operationId: createNote
      tags: [Encounters]
      summary: Create a clinical note (encounter)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Note'
      responses:
        '201':
          description: Created
    get:
      operationId: searchNotes
      tags: [Encounters]
      summary: Search clinical notes
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: status
          in: query
          schema: { type: string, enum: [preliminary, final] }
        - name: service_date_start
          in: query
          schema: { type: string, format: date }
        - name: limit
          in: query
          schema: { type: integer }
        - name: offset
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: OK
  /notes/{note_id}:
    get:
      operationId: getNote
      tags: [Encounters]
      summary: Get a clinical note by id
      parameters:
        - name: note_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
  /tasks:
    post:
      operationId: createTask
      tags: [Tasks]
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '201':
          description: Created
    get:
      operationId: searchTasks
      tags: [Tasks]
      summary: Search tasks
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: owner_id
          in: query
          schema: { type: string }
        - name: status
          in: query
          schema:
            type: array
            items:
              type: string
              enum: [not-started, in-progress, completed]
        - name: priority
          in: query
          schema: { type: string, enum: [p1, p2, p3] }
        - name: due_date
          in: query
          schema: { type: string, format: date }
        - name: archived
          in: query
          schema: { type: boolean }
        - name: limit
          in: query
          schema: { type: integer }
        - name: offset
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: OK
  /tasks/{task_id}:
    get:
      operationId: getTask
      tags: [Tasks]
      summary: Get a task by id
      parameters:
        - name: task_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
    put:
      operationId: updateTask
      tags: [Tasks]
      summary: Update a task
      parameters:
        - name: task_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: OK
  /documents:
    post:
      operationId: createDocument
      tags: [Documents]
      summary: Upload a document
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                patient_id:
                  type: string
      responses:
        '201':
          description: Created
    get:
      operationId: searchDocuments
      tags: [Documents]
      summary: Search documents
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: no_patient
          in: query
          schema: { type: boolean }
        - name: sort
          in: query
          schema: { type: string, example: 'created_at:asc' }
        - name: limit
          in: query
          schema: { type: integer }
        - name: offset
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: OK
  /documents/{document_id}:
    get:
      operationId: getDocument
      tags: [Documents]
      summary: Get a document by id
      parameters:
        - name: document_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
  /medications:
    get:
      operationId: searchMedications
      tags: [Medications]
      summary: Search medications or list a patient's medications
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: search_term
          in: query
          schema: { type: string }
        - name: start_date
          in: query
          schema: { type: string, format: date }
        - name: end_date
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: OK
  /medications/select:
    get:
      operationId: selectDispensableDrug
      tags: [Medications]
      summary: Look up a dispensable drug
      parameters:
        - name: dispensable_drug_id
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
  /medications/history:
    get:
      operationId: getMedicationHistory
      tags: [Medications]
      summary: Retrieve Surescripts medication history
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: prescriber_user_id
          in: query
          schema: { type: string }
        - name: start_date
          in: query
          schema: { type: string, format: date }
        - name: end_date
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: OK
  /medications/history/cached:
    get:
      operationId: getCachedMedicationHistory
      tags: [Medications]
      summary: Retrieve cached medication history
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
      responses:
        '200':
          description: OK
  /procedures:
    get:
      operationId: searchProcedures
      tags: [Labs]
      summary: Search lab procedures
      parameters:
        - name: query
          in: query
          schema: { type: string }
        - name: performer_organization_id
          in: query
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer }
        - name: offset
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: OK
  /facilities:
    get:
      operationId: searchFacilities
      tags: [Labs]
      summary: Search lab facilities
      parameters:
        - name: name
          in: query
          schema: { type: string }
        - name: zipcode
          in: query
          schema: { type: string }
        - name: distance
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: OK
  /orders:
    post:
      operationId: createOrder
      tags: [Labs]
      summary: Create a lab order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
        '202':
          description: Accepted (pending)
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_id: { type: string }
    get:
      operationId: searchOrders
      tags: [Labs]
      summary: Search lab orders
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: authoring_user_id
          in: query
          schema: { type: string }
        - name: start_date_range
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: OK
  /orders/{order_id}:
    get:
      operationId: getOrder
      tags: [Labs]
      summary: Get a lab order by id
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: OK
  /orders/requests/{order_request_id}:
    get:
      operationId: getOrderRequest
      tags: [Labs]
      summary: Get a lab order request status
      parameters:
        - name: order_request_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
  /orders/{order_id}/pdf:
    get:
      operationId: getOrderPdf
      tags: [Labs]
      summary: Get a lab order requisition PDF
      parameters:
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: OK
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  /diagnosticreport:
    get:
      operationId: searchDiagnosticReports
      tags: [Labs]
      summary: Search diagnostic reports
      parameters:
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: order_id
          in: query
          schema: { type: string }
        - name: start_date_range
          in: query
          schema: { type: string, format: date }
        - name: limit
          in: query
          schema: { type: integer }
        - name: offset
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: OK
  /diagnosticreport/{diagnostic_report_id}:
    get:
      operationId: getDiagnosticReport
      tags: [Labs]
      summary: Get a diagnostic report by id
      parameters:
        - $ref: '#/components/parameters/DiagnosticReportId'
      responses:
        '200':
          description: OK
    put:
      operationId: updateDiagnosticReport
      tags: [Labs]
      summary: Update a diagnostic report
      parameters:
        - $ref: '#/components/parameters/DiagnosticReportId'
      responses:
        '200':
          description: OK
  /diagnosticreport/{diagnostic_report_id}/pdf:
    get:
      operationId: getDiagnosticReportPdf
      tags: [Labs]
      summary: Get a diagnostic report PDF
      parameters:
        - $ref: '#/components/parameters/DiagnosticReportId'
      responses:
        '200':
          description: OK
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  /observations:
    get:
      operationId: searchObservations
      tags: [Labs]
      summary: Search observations (lab results, vital signs)
      parameters:
        - name: category
          in: query
          schema: { type: string, enum: [laboratory, vital-signs] }
        - name: patient_id
          in: query
          schema: { type: string }
        - name: external_patient_id
          in: query
          schema: { type: string }
        - name: diagnostic_report_id
          in: query
          schema: { type: string }
        - name: order_id
          in: query
          schema: { type: string }
      responses:
        '200':
          description: OK
  /observations/{observation_id}:
    get:
      operationId: getObservation
      tags: [Labs]
      summary: Get an observation by id
      parameters:
        - name: observation_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
  /webhooks:
    get:
      operationId: listWebhooks
      tags: [Webhooks]
      summary: List webhook subscriptions
      parameters:
        - name: start_time
          in: query
          schema: { type: string, format: date-time }
        - name: end_time
          in: query
          schema: { type: string, format: date-time }
      responses:
        '200':
          description: OK
  /webhooks/{webhook_id}:
    get:
      operationId: getWebhook
      tags: [Webhooks]
      summary: Get a webhook subscription by id
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
    post:
      operationId: updateWebhook
      tags: [Webhooks]
      summary: Update a webhook subscription
      parameters:
        - name: webhook_id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key created on the Settings -> Developer page in Akute. Required on
        every request.
  parameters:
    PatientId:
      name: patient_id
      in: path
      required: true
      schema: { type: string }
    AppointmentId:
      name: appointment_id
      in: path
      required: true
      schema: { type: string }
    OrderId:
      name: order_id
      in: path
      required: true
      schema: { type: string }
    DiagnosticReportId:
      name: diagnostic_report_id
      in: path
      required: true
      schema: { type: string }
  schemas:
    Patient:
      type: object
      properties:
        id: { type: string }
        external_id: { type: string }
        first_name: { type: string }
        middle_name: { type: string }
        last_name: { type: string }
        date_of_birth: { type: string, format: date }
        sex: { type: string, enum: [male, female, other, unknown] }
        status: { type: string, enum: [active, inactive] }
        email: { type: string, format: email }
        primary_phone_number: { type: string }
        primary_phone_type: { type: string, enum: [mobile, home, work] }
        address_line_1: { type: string }
        address_line_2: { type: string }
        address_city: { type: string }
        address_state: { type: string }
        address_zipcode: { type: string }
    PatientCreate:
      type: object
      required: [first_name, last_name, date_of_birth, sex, status]
      properties:
        external_id: { type: string }
        first_name: { type: string }
        middle_name: { type: string }
        last_name: { type: string }
        date_of_birth: { type: string, format: date }
        sex: { type: string, enum: [male, female, other, unknown] }
        status: { type: string, enum: [active, inactive] }
        email: { type: string, format: email }
        primary_phone_number: { type: string }
        primary_phone_type: { type: string, enum: [mobile, home, work] }
        address_line_1: { type: string }
        address_line_2: { type: string }
        address_city: { type: string }
        address_state: { type: string }
        address_zipcode: { type: string }
    Appointment:
      type: object
      properties:
        id: { type: string }
        patient_id: { type: string }
        external_patient_id: { type: string }
        practitioner_user_id: { type: string }
        appointment_type_id: { type: string }
        start_time: { type: string, format: date-time }
        end_time: { type: string, format: date-time }
        status: { type: string, enum: [booked, fulfilled, cancelled, noshow] }
        description: { type: string }
    Note:
      type: object
      required: [type, authors, sections]
      properties:
        id: { type: string }
        type:
          type: string
          description: Type of note (e.g. Progress note, Phone note).
        patient_id: { type: string }
        external_patient_id: { type: string }
        service_date: { type: string, format: date }
        status: { type: string, enum: [preliminary, final] }
        signed:
          type: object
          properties:
            user_id: { type: string }
        authors:
          type: array
          items:
            type: object
            properties:
              user_id: { type: string }
        sections:
          type: array
          items:
            type: object
            properties:
              title: { type: string }
              text: { type: string }
    Task:
      type: object
      required: [task]
      properties:
        id: { type: string }
        task: { type: string }
        description: { type: string }
        due_date: { type: string, format: date }
        owner_id: { type: string }
        patient_id: { type: string }
        priority: { type: string, enum: [p1, p2, p3] }
        status: { type: string, enum: [not-started, in-progress, completed] }
        tags:
          type: array
          items: { type: string }
    OrderCreate:
      type: object
      required: [procedures]
      properties:
        patient_id: { type: string }
        external_patient_id: { type: string }
        procedures:
          type: array
          items: { type: string }
        billing_type: { type: string }
        delivery_option: { type: string }
        ordering_user_id: { type: string }
        performer_organization_id: { type: string }
        account_number: { type: string }
        diagnoses:
          type: array
          items: { type: string }
    Webhook:
      type: object
      properties:
        id: { type: string }
        resource:
          type: string
          enum:
            - patients
            - appointments
            - notes
            - tasks
            - medications
            - medicationPriorAuths
            - diagnosticReports
            - orders
            - orderRequests
            - faxes
            - conversations
            - conversationMessages
        event:
          type: string
          enum: [create, update, request]
        destination: { type: string, format: uri }
        secret: { type: string }