openapi: 3.2.0
info:
  version: 2.0.0
  title: Rest-Service Outbound Referrals API
  x-logo:
    url: https://lumahealth-assets.s3.us-west-2.amazonaws.com/new_luma_logo_black.png
    backgroundColor: '#FFFFFF'
    altText: Luma Health
  description: OpenAPI [Basic Structure](https://swagger.io/docs/specification/basic-structure/)
servers:
- url: https://api.lumahealth.io/api/v2
security:
- Bearer: []
tags:
- name: outboundReferrals
  description: Outbound Referral
paths:
  /outboundReferrals:
    get:
      summary: List OutboundReferrals
      operationId: outboundReferralsList
      tags:
      - outboundReferrals
      parameters:
      - name: _id
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/deletedParam'
      - $ref: '#/components/parameters/createdByParam'
      - $ref: '#/components/parameters/updatedByParam'
      - $ref: '#/components/parameters/deletedByParam'
      - $ref: '#/components/parameters/createdAtParam'
      - $ref: '#/components/parameters/updatedAtParam'
      - $ref: '#/components/parameters/deletedAtParam'
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/populateParam'
      - $ref: '#/components/parameters/selectParam'
      responses:
        '200':
          description: List of outbound referrals
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                - page
                - size
                properties:
                  response:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/OutboundReferralsResponse'
                  page:
                    type: integer
                    format: int32
                    minimum: 1
                  size:
                    type: integer
                    format: int32
                    minimum: 0
                additionalProperties: false
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    post:
      summary: Create OutboundReferrals
      operationId: outboundReferralsCreate
      tags:
      - outboundReferrals
      requestBody:
        description: Create an outbound referral
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundReferralsCreate'
      responses:
        '201':
          description: Successful creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundReferralsResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /outboundReferrals/{outboundReferralsId}:
    get:
      summary: Get a OutboundReferral by id
      operationId: outboundReferralById
      tags:
      - outboundReferrals
      parameters:
      - name: outboundReferralId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: OutboundReferral
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundReferralsResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    put:
      summary: Update a OutboundReferral
      operationId: outboundReferralUpdate
      tags:
      - outboundReferrals
      parameters:
      - name: outboundReferralId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      requestBody:
        description: A outboundReferral (full or partial) to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundReferralsUpdate'
      responses:
        '200':
          description: OutboundReferral
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundReferralsResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    delete:
      summary: Delete a OutboundReferral
      operationId: outboundReferralDelete
      tags:
      - outboundReferrals
      parameters:
      - name: outboundReferralId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Deleted outboundReferral
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundReferralsResponse'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
components:
  parameters:
    pageParam:
      in: query
      name: page
      required: false
      type: integer
      format: int32
      default: 1
      minimum: 1
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    createdAtParam:
      in: query
      name: createdAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was created.
    updatedAtParam:
      in: query
      name: updatedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was updated.
    updatedByParam:
      in: query
      name: updatedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who updated this object.
    createdByParam:
      in: query
      name: createdBy
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      required: false
      description: The ID of the user who created this object.
    deletedByParam:
      in: query
      name: deletedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who deleted this object.
    populateParam:
      name: _populate
      in: query
      description: Response properties which will be replaced by the referenced objects, separated by commas.
      required: false
      type: string
      schema:
        type: string
    selectParam:
      name: _select
      in: query
      description: Response properties that should be returned, separated by commas.
      required: false
      type: string
      schema:
        type: string
    deletedParam:
      in: query
      name: deleted
      required: false
      type: number
      enum:
      - 0
      - 1
      schema:
        type: number
        enum:
        - 0
        - 1
      description: Flag for logical deletion where 1 means deleted.
    deletedAtParam:
      in: query
      name: deletedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was deleted.
    limitParam:
      name: limit
      in: query
      description: How many items to fetch per page
      required: false
      type: integer
      format: int32
      default: 500
      minimum: 1
      maximum: 1000
      schema:
        type: integer
        format: int32
        default: 500
        minimum: 1
        maximum: 1000
    userParam:
      in: query
      name: user
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the root account user.
  schemas:
    OutboundReferralsCreate:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        facility:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        provider:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        renderingProvider:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        appointmentType:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        source:
          type: string
          enum:
          - upload
          - ui
          - integrator
        status:
          type: string
          enum:
          - active
          - called
          - scheduled
          - incomplete
          - cancelled
          - expired
          - closed
        diagnoses:
          type: array
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        attempt:
          type: int32
        startOn:
          type: string
          format: date-time
        expireAt:
          type: string
          format: date-time
        lastAttemptAt:
          type: string
          format: date-time
        calledAt:
          type: string
          format: date-time
        notes:
          type: string
        reason:
          type: string
        processedReferallOutreach:
          type: string
          enum:
          - pending
          - skipped
          - failed
          - success
        faxUpload:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        externalId:
          $ref: '#/components/schemas/ExternalId'
    userParam:
      in: query
      name: user
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the root account user.
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    OutboundReferralsResponse:
      type: object
      description: An Outbound Referral represents a referral sent from a practice to an outside provider or facility on behalf of a patient, for example when a primary care office refers a patient to a specialist. It tracks the referring and rendering providers, the receiving facility, the associated diagnoses and appointment type, and how the referral entered the system such as by upload, manual entry, or integration. It also tracks the outreach lifecycle including attempts to contact the patient, expiration, and status values like active, called, scheduled, or closed.
      properties:
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        deletedBy:
          $ref: '#/components/schemas/deletedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        deletedAt:
          $ref: '#/components/schemas/deletedAtParam'
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        facility:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        provider:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        renderingProvider:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        appointmentType:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        source:
          type: string
          enum:
          - upload
          - ui
          - integrator
        status:
          type: string
          enum:
          - active
          - called
          - scheduled
          - incomplete
          - cancelled
          - expired
          - closed
        diagnoses:
          type: array
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        attempt:
          type: int32
        startOn:
          type: string
          format: date-time
        expireAt:
          type: string
          format: date-time
        lastAttemptAt:
          type: string
          format: date-time
        calledAt:
          type: string
          format: date-time
        notes:
          type: string
        reason:
          type: string
        processedReferallOutreach:
          type: string
          enum:
          - pending
          - skipped
          - failed
          - success
        faxUpload:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        externalId:
          $ref: '#/components/schemas/ExternalId'
    OutboundReferralsUpdate:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        facility:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        provider:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        renderingProvider:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        appointmentType:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        source:
          type: string
          enum:
          - upload
          - ui
          - integrator
        status:
          type: string
          enum:
          - active
          - called
          - scheduled
          - incomplete
          - cancelled
          - expired
          - closed
        diagnoses:
          type: array
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        attempt:
          type: int32
        startOn:
          type: string
          format: date-time
        expireAt:
          type: string
          format: date-time
        lastAttemptAt:
          type: string
          format: date-time
        calledAt:
          type: string
          format: date-time
        notes:
          type: string
        reason:
          type: string
        processedReferallOutreach:
          type: string
          enum:
          - pending
          - skipped
          - failed
          - success
        faxUpload:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        externalId:
          $ref: '#/components/schemas/ExternalId'
    idParam:
      in: query
      name: _id
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      required: false
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: Luma's internal ID of an object.
    deletedAtParam:
      in: query
      name: deletedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was deleted.
    updatedAtParam:
      in: query
      name: updatedAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was updated.
    createdAtParam:
      in: query
      name: createdAt
      type: string
      format: date-time
      schema:
        type: string
        format: date-time
      required: false
      description: The date/time when this object was created.
    updatedByParam:
      in: query
      name: updatedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who updated this object.
    ExternalId:
      type: object
      properties:
        source:
          description: externalId.source
          type: string
          enum:
          - gcalendar
          - successehs
          - drchrono
          - dentrix
          - webpt
          - theraoffice
          - mi7
          - practicefusion
          - advancedmd
          - acomrapidpm
          - kareo
          - nextech
          - mwtherapy
          - clinicient
          - carecloud
          - eclinicalmobile
          - duxware
          - labretriever
          - optimispt
          - referral
          - recall
          - allscriptspm
          - lytec
          - brightree
          - fullslate
          - nuemd
          - centricityps
          - officeally
          - greenwayintergy
          - compulink
          - adspm
          - dsnpm
          - lumamock
          - medicalmastermind
          - meditouch
          - healthnautica
          - ezemrx
          - hl7
          - amazingcharts
          - greenwayprimesuite
          - raintree
          - athenahealth
          - revflow
          - eclinicalworks10e
          - hl7pickup
          - mindbody
          - eclinicalworkssql
          - nextgen
          - practiceperfect
          - avimark
          - clinix
          - keymedical
          - mdoffice
          - webedoctor
          - emapm
          - medinformatix
          - imsgo
          - emds
          - allscriptsunity
          - medevolve
          - caretracker
          - clearpractice
          - valant
          - micromd
          - systemedx
          - medicalmaster
          - athenamdp
          - gmed
          - roche
          - onetouch
          - somnoware
          - managementplus
          - lumacare
          - nextechfhir
          - curemd
          - epic
          - phoenixortho
          - ezderm
          - ggastromobile
          - epicconfirmationpickup
          - cerner
          - allmeds
          - oncoemrfilepickup
          - imedicware
          - modmedfhir
          - clinux
          - acuityscheduling
          - medstreaming
          - isalus
          - meditechexpanse
          - openemr
          - genericfhir
          - nextechpracticeplus
          - sms
          - voice
          - email
          - none
        value:
          description: externalId.value
          type: string
    deletedParam:
      in: query
      name: deleted
      required: false
      type: number
      enum:
      - 0
      - 1
      schema:
        type: number
        enum:
        - 0
        - 1
      description: Flag for logical deletion where 1 means deleted.
    createdByParam:
      in: query
      name: createdBy
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      required: false
      description: The ID of the user who created this object.
    deletedByParam:
      in: query
      name: deletedBy
      required: false
      type: string
      pattern: '[0-9a-f]'
      minLength: 24
      maxLength: 24
      schema:
        type: string
        pattern: '[0-9a-f]'
        minLength: 24
        maxLength: 24
      description: The ID of the user who deleted this object.
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT