openapi: 3.1.0
info:
  title: Apex Odonto Dental EHR API
  version: 1.0.0
  summary: FHIR R4 partner API for Apex Odonto — dental practice and DSO workflows
  description: |
    **Apex Odonto™** is Parker Apex's FHIR-first Dental EHR product line. Partners integrate via
    the shared gateway at `api.parkerapex.com/fhir/R4` with GPID-scoped OAuth and required headers.

    Clinical workflows include odontogram/tooth charting, periodontal charting, treatment plans,
    dental procedures, imaging attachments, lab/appliance orders, eligibility, and dental claim
    type (`oral`).

    Tooth and surface details use Parker extensions where standard FHIR is insufficient:
    - `https://schemas.parkerapex.com/fhir/StructureDefinition/tooth-number`
    - `https://schemas.parkerapex.com/fhir/StructureDefinition/tooth-surface`

    **Golden bundle:** `docs/schemas/specialty/odonto-golden-bundle.r4.json`
    **Product code:** `odonto` · **Claim type:** `oral`

    Required partner headers on every write:
    - `X-Apex-Actor-GPID` — organizational actor GPID
    - `X-Apex-Subject-GPID` — patient GPID
    - `X-Apex-Source` — integration source identifier
servers:
  - url: https://api.parkerapex.com/fhir/R4
    description: Production FHIR gateway (Odonto scope)
  - url: https://lake.parkerapex.com/fhir/R4
    description: FHIR Data Lake (longitudinal store)
  - url: https://sandbox.api.parkerapex.com/fhir/R4
    description: Sandbox
tags:
  - name: Identity
  - name: Scheduling
  - name: Clinical
  - name: Charting
  - name: Imaging
  - name: Lab
  - name: Financial
  - name: Conformance
security:
  - OAuth2: []
paths:
  /metadata:
    get:
      tags: [Conformance]
      operationId: odontoCapabilityStatement
      summary: FHIR CapabilityStatement (dental resource set)
      security: []
      responses:
        '200':
          description: CapabilityStatement (application/fhir+json)
  /Patient:
    get:
      tags: [Identity]
      operationId: searchOdontoPatients
      summary: Search dental patients by GPID or demographics
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: identifier
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Bundle of Patient resources
    post:
      tags: [Identity]
      operationId: createOdontoPatient
      summary: Create patient (IdentityResolver required)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Patient created
  /Appointment:
    get:
      tags: [Scheduling]
      operationId: searchOdontoAppointments
      summary: Search chair appointments and hygiene recall
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          schema: { type: string }
        - name: date
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Bundle of Appointment resources
    post:
      tags: [Scheduling]
      operationId: createOdontoAppointment
      summary: Book dental appointment
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Appointment created
  /Encounter:
    post:
      tags: [Clinical]
      operationId: createOdontoEncounter
      summary: Open dental visit encounter
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Encounter created
  /Observation:
    get:
      tags: [Charting]
      operationId: searchOdontoObservations
      summary: Search odontogram and periodontal chart observations
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
        - name: code
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Bundle of Observation resources (tooth/surface extensions)
    post:
      tags: [Charting]
      operationId: createOdontoObservation
      summary: Record tooth chart or periodontal finding
      description: |
        Use tooth-number and tooth-surface extensions on Observation for odontogram entries.
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Observation created
  /Procedure:
    get:
      tags: [Clinical]
      operationId: searchOdontoProcedures
      summary: Search completed dental procedures (CDT-coded)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Bundle of Procedure resources
    post:
      tags: [Clinical]
      operationId: createOdontoProcedure
      summary: Post completed dental procedure
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Procedure created
  /CarePlan:
    get:
      tags: [Clinical]
      operationId: searchOdontoCarePlans
      summary: Search treatment plans
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Bundle of CarePlan resources
    post:
      tags: [Clinical]
      operationId: createOdontoCarePlan
      summary: Create dental treatment plan
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: CarePlan created
  /DocumentReference:
    post:
      tags: [Imaging]
      operationId: createOdontoDocumentReference
      summary: Attach bitewing, panoramic, CBCT, or intraoral image
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: DocumentReference created
  /DiagnosticReport:
    post:
      tags: [Imaging]
      operationId: createOdontoDiagnosticReport
      summary: Submit radiology narrative or grouped imaging report
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: DiagnosticReport created
  /ServiceRequest:
    post:
      tags: [Lab]
      operationId: createOdontoServiceRequest
      summary: Order lab work (crown, bridge, aligner, denture)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: ServiceRequest created
  /DeviceRequest:
    post:
      tags: [Lab]
      operationId: createOdontoDeviceRequest
      summary: Order dental appliance (night guard, retainer, aligner)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: DeviceRequest created
  /CoverageEligibilityRequest:
    post:
      tags: [Financial]
      operationId: createOdontoEligibilityRequest
      summary: Dental benefits check (preventive, restorative, perio, ortho)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: CoverageEligibilityRequest created
  /Claim:
    post:
      tags: [Financial]
      operationId: createOdontoClaim
      summary: Submit dental claim or preauthorization (Claim.type = oral)
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - $ref: '#/components/parameters/XApexSource'
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema: { type: object }
      responses:
        '201':
          description: Claim created
  /ClaimResponse:
    get:
      tags: [Financial]
      operationId: readOdontoClaimResponse
      summary: Read payer adjudication for dental claim
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: _id
          in: query
          schema: { type: string }
      responses:
        '200':
          description: ClaimResponse resource
  /ExplanationOfBenefit:
    get:
      tags: [Financial]
      operationId: searchOdontoEob
      summary: Search dental EOBs for patient
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patient
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Bundle of ExplanationOfBenefit resources

  /odonto/v1/chart/{patientGpid}:
    get:
      tags: [Operational]
      operationId: getOdontoChart
      summary: Get odontogram and periodontal chart for patient
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - name: patientGpid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Tooth chart with surfaces and perio measurements
    put:
      tags: [Operational]
      operationId: updateOdontoChart
      summary: Update tooth/surface findings (maps to FHIR Observations)
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
        - name: patientGpid
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Chart updated
  /odonto/v1/treatment-plans:
    post:
      tags: [Operational]
      operationId: createOdontoTreatmentPlan
      summary: Create dental treatment plan (CarePlan + Tasks)
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
      responses:
        '201':
          description: Treatment plan created
  /odonto/v1/procedures/post:
    post:
      tags: [Operational]
      operationId: postOdontoProcedure
      summary: Post completed CDT-coded procedure to chart and claim queue
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
      responses:
        '201':
          description: Procedure posted
  /odonto/v1/lab/orders:
    post:
      tags: [Operational]
      operationId: createOdontoLabOrder
      summary: Order crown, bridge, aligner, or denture from external lab
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
      responses:
        '202':
          description: Lab order accepted
  /odonto/v1/imaging/upload:
    post:
      tags: [Operational]
      operationId: uploadOdontoImaging
      summary: Upload bitewing, panoramic, CBCT, or intraoral image
      servers: [{ url: https://api.parkerapex.com }]
      parameters:
        - $ref: '#/components/parameters/XApexActorGpid'
        - $ref: '#/components/parameters/XApexSubjectGpid'
      responses:
        '202':
          description: Imaging ingest accepted

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.parkerapex.com/oauth/token
          scopes:
            user/Patient.read: Read patients
            user/Patient.write: Create/update patients
            user/Procedure.read: Read procedures
            user/Procedure.write: Write procedures
            user/CarePlan.read: Read treatment plans
            user/CarePlan.write: Write treatment plans
            user/Claim.write: Submit claims
  parameters:
    XApexActorGpid:
      name: X-Apex-Actor-GPID
      in: header
      required: true
      schema: { type: string }
      description: Partner organizational actor GPID (PLX-…)
    XApexSubjectGpid:
      name: X-Apex-Subject-GPID
      in: header
      required: true
      schema: { type: string }
      description: Patient GPID (APX-…)
    XApexSource:
      name: X-Apex-Source
      in: header
      required: true
      schema: { type: string }
      description: Integration source identifier (e.g. odonto-partner-001)
