openapi: 3.0.3
info:
  title: Updox IO API (Modeled)
  version: '1.0'
  description: >-
    Modeled OpenAPI for the confirmed actions of the Updox "IO" API. Updox
    exposes a POST-based partner API surfaced through an IO Docs explorer
    (https://updoxqa.com/api/newio) with tiered application / account / user
    authentication. This document transcribes only the actions confirmed in the
    IO Docs explorer and knowledge base (Ping health checks, Address Book
    contacts, Faxing poll functions, and Video Chat actions); request/response
    bodies are modeled from the documented behavior, not a machine-readable
    Updox spec. Updox is part of EverCommerce (NASDAQ - EVCM).
  contact:
    name: Updox Support
    url: https://www.updox.com/support/
  x-modeled: true
servers:
  - url: https://updoxqa.com/api/io
    description: Updox IO Docs / QA reference host (production base is provisioned per partner)
tags:
  - name: Ping
    description: Connectivity and authentication health checks.
  - name: Address Book
    description: Practice-level contact/address-book actions.
  - name: Faxing
    description: Inbound electronic fax retrieval.
  - name: Video Chat
    description: Telehealth video call actions.
paths:
  /Ping:
    post:
      tags: [Ping]
      summary: Ping (no authentication)
      description: Unauthenticated connectivity check.
      operationId: ping
      responses:
        '200':
          description: Service reachable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
  /PingWithApplicationAuth:
    post:
      tags: [Ping]
      summary: Ping with application authentication
      operationId: pingWithApplicationAuth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationAuth'
      responses:
        '200':
          description: Application credentials validated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
  /PingWithAccountAuth:
    post:
      tags: [Ping]
      summary: Ping with application + account authentication
      operationId: pingWithAccountAuth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountAuth'
      responses:
        '200':
          description: Application + account credentials validated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
  /PingWithAuth:
    post:
      tags: [Ping]
      summary: Ping with full authentication (application + account + user)
      operationId: pingWithAuth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FullAuth'
      responses:
        '200':
          description: Full credentials validated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
  /AddressBookList:
    post:
      tags: [Address Book]
      summary: List address book contacts
      description: Get all contacts associated with the supplied account.
      operationId: addressBookList
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountAuth'
      responses:
        '200':
          description: Contacts for the account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
  /AddressBookSearch:
    post:
      tags: [Address Book]
      summary: Search the practice address book
      description: Search the practice-level address book by criteria.
      operationId: addressBookSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/AccountAuth'
                - type: object
                  properties:
                    searchCriteria:
                      type: string
                      description: Name, phone, or other match criteria.
      responses:
        '200':
          description: Matching contacts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactList'
  /ContactCreate:
    post:
      tags: [Address Book]
      summary: Create a contact
      description: Create a contact with the supplied information.
      operationId: contactCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/AccountAuth'
                - $ref: '#/components/schemas/Contact'
      responses:
        '200':
          description: Contact created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
  /FaxOemPop:
    post:
      tags: [Faxing]
      summary: Retrieve next inbound fax (PNG)
      description: >-
        Multifunction poll. Reports whether inbound faxes are queued, returns the
        oldest unhandled fax image (PNG) in the response, and marks the prior fax
        handled via lastRetrievedFaxId. Repeat until endOfQueue is true.
      operationId: faxOemPop
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FaxPopRequest'
      responses:
        '200':
          description: Fax payload or end-of-queue marker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaxPopResponse'
  /PopPDF:
    post:
      tags: [Faxing]
      summary: Retrieve next inbound fax (PDF)
      description: Same behavior and parameters as FaxOemPop, but returns the fax as a PDF.
      operationId: popPdf
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FaxPopRequest'
      responses:
        '200':
          description: Fax payload or end-of-queue marker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaxPopResponse'
  /VideoCallActions:
    post:
      tags: [Video Chat]
      summary: Video call actions (SendInvite / retrieval)
      description: >-
        Telehealth video actions. SendInvite invites a patient into an Updox
        Video Chat session; retrieval actions return call state. The action is
        selected by the request body.
      operationId: videoCallActions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/FullAuth'
                - type: object
                  properties:
                    action:
                      type: string
                      enum: [SendInvite, GetCall, ListCalls]
                    patientId:
                      type: string
                    phoneOrEmail:
                      type: string
                      description: Destination for the video invite.
      responses:
        '200':
          description: Action result (invite confirmation or call state).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    ApplicationAuth:
      type: object
      required: [applicationId, applicationPassword]
      properties:
        applicationId:
          type: string
        applicationPassword:
          type: string
    AccountAuth:
      allOf:
        - $ref: '#/components/schemas/ApplicationAuth'
        - type: object
          required: [accountId]
          properties:
            accountId:
              type: string
    FullAuth:
      allOf:
        - $ref: '#/components/schemas/AccountAuth'
        - type: object
          required: [userId]
          properties:
            userId:
              type: string
    PingResponse:
      type: object
      properties:
        status:
          type: string
          example: ok
        timestamp:
          type: string
          format: date-time
    Contact:
      type: object
      properties:
        contactId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        organization:
          type: string
        phone:
          type: string
        fax:
          type: string
        email:
          type: string
        address:
          type: string
    ContactList:
      type: object
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
    FaxPopRequest:
      allOf:
        - $ref: '#/components/schemas/AccountAuth'
        - type: object
          properties:
            lastRetrievedFaxId:
              type: string
              description: >-
                ID of the previously retrieved fax, marking it handled so the
                next unhandled fax is returned. Omit on the first call.
    FaxPopResponse:
      type: object
      properties:
        faxId:
          type: string
        endOfQueue:
          type: boolean
          description: True when no more unhandled faxes remain.
        contentType:
          type: string
          enum: [image/png, application/pdf]
        content:
          type: string
          format: byte
          description: Base64-encoded fax image, present when a fax is available.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com