Luma Health Referrals API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Rest-Service 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: referrals
  description: Luma Patient referrals
paths:
  /referrals/{referralId}:
    get:
      summary: Get a referral by id
      operationId: referralGet
      tags:
      - referrals
      parameters:
      - name: referralId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: A referral
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    put:
      summary: Update a referral
      operationId: referralUpdate
      tags:
      - referrals
      parameters:
      - name: referralId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      requestBody:
        description: A referral (full or partial) to be updated
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Referral'
      responses:
        '200':
          description: Updated referral
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
    delete:
      summary: Delete a referral
      operationId: referralDelete
      tags:
      - referrals
      parameters:
      - name: referralId
        in: path
        required: true
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      responses:
        '200':
          description: Deleted referral
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /referrals:
    get:
      summary: List referrals
      operationId: referralsList
      tags:
      - referrals
      parameters:
      - $ref: '#/components/parameters/idParam'
      - $ref: '#/components/parameters/userParam'
      - $ref: '#/components/parameters/deletedParam'
      - $ref: '#/components/parameters/createdByParam'
      - $ref: '#/components/parameters/updatedByParam'
      - $ref: '#/components/parameters/createdAtParam'
      - $ref: '#/components/parameters/updatedAtParam'
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/populateParam'
      - $ref: '#/components/parameters/selectParam'
      - name: facility
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: provider
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: patient
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: referringProviderId
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: referringProvider
        in: query
        description: The name of the referring provider
        schema:
          type: string
      - name: duration
        description: Optional duration for how long the patient should be seen for
        in: query
        schema:
          type: number
          format: int32
      - name: statusReason
        in: query
        description: Reason why there's a status update to this referral
        schema:
          type: string
          enum:
          - patient-cancelled
          - invalid-insurance
          - missing-data
          - other
      - name: statusReasonDescription
        in: query
        description: Free text explaining more details about closing chat activities
        schema:
          type: string
      - name: source
        in: query
        schema:
          type: string
          enum:
          - upload
          - patient-referral-form
          - ui
          - integrator
          - followup
          - manual
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - called
          - called-late
          - scheduled
          - scheduled-late
          - incomplete
          - expired
          - cancelled
          - pending
          - closed
      - name: startOn
        in: query
        schema:
          type: string
          format: date-time
      - name: expireAt
        in: query
        schema:
          type: string
          format: date-time
      - name: attempt
        in: query
        schema:
          type: number
          format: int32
      - name: lastAttemptSentAt
        in: query
        schema:
          type: string
          format: date-time
      - name: calledAt
        in: query
        schema:
          type: string
          format: date-time
      - name: acceptedAt
        in: query
        schema:
          type: string
          format: date-time
      - name: scheduledAt
        in: query
        schema:
          type: string
          format: date-time
      - name: notes
        in: query
        schema:
          type: string
      - name: customerNotes
        in: query
        schema:
          type: string
      - name: appointmentType
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: reason
        in: query
        schema:
          type: string
      - name: departmentOrFacility
        description: When the costumer has multiple departments/facilities, this field makes it easier to handle where the referral should go
        in: query
        schema:
          type: string
      - name: scheduledByAppointment
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: scheduledByOffer
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: processedReferralFollowup
        in: query
        schema:
          type: string
          enum:
          - pending
          - skipped
          - failed
          - success
      - name: upload
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: faxUpload
        in: query
        schema:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
      - name: faxSentAt
        in: query
        schema:
          type: string
          format: date-time
      - name: scheduleStartOn
        in: query
        schema:
          type: string
          format: date-time
      - name: referringProviderFaxNumberOverride
        in: query
        description: If set, the fax sent back to the referring provider will be sent to this value instead of the fax contact on the referring provider record.
        schema:
          type: string
      responses:
        '200':
          description: List of referrals
          content:
            application/json:
              schema:
                type: object
                required:
                - response
                - page
                - size
                properties:
                  response:
                    type: array
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/Referral'
                  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 referral
      operationId: referralCreate
      tags:
      - referrals
      requestBody:
        description: Create a referral
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Referral'
      responses:
        '201':
          description: Successful creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Referral'
        '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'
  /referrals/inbound:
    post:
      summary: Get a list of referrals
      tags:
      - referrals
      requestBody:
        description: Request body description will be here
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                page:
                  $ref: '#/components/schemas/pageParam'
                limit:
                  $ref: '#/components/schemas/limitParam'
                dateFrom:
                  type: string
                  format: date
                  description: If this is missing, it will take the value of dateTo.
                dateTo:
                  type: string
                  format: date
                  description: If this field is missing, the default date is today.
                search:
                  type: string
                  minLength: 3
                  maxLength: 15
                filterFacility:
                  description: Filter out the facilities by their ids.
                  type: array
                  minItems: 0
                  maxItems: 20
                  items:
                    type: string
                filterAppointment:
                  type: array
                  minItems: 0
                  maxItems: 10
                  items:
                    type: string
                filterReferringProvider:
                  description: Default filter is `any`. If list of referring provider ids are given, resulting response will remove those providers.
                  type: array
                  minItems: 0
                  maxItems: 10
                  items:
                    type: string
                statuses:
                  type: array
                  items:
                    type: string
                    enum:
                    - active
                    - called
                    - called-late
                    - scheduled
                    - scheduled-late
                    - incomplete
                    - expired
                    - cancelled
                    - pending
                    - closed
              additionalProperties: false
      responses:
        '200':
          description: Returns a list of referrals after applying the filters
          content:
            application/json:
              schema:
                type: object
                required:
                - referrals
                - page
                - totalCount
                properties:
                  referrals:
                    type: array
                    minItems: 0
                    items:
                      type: object
                      properties:
                        patient:
                          $ref: '#/components/schemas/PatientResponse'
                        facility:
                          $ref: '#/components/schemas/FacilityResponse'
                        status:
                          type: string
                          enum:
                          - active
                          - called
                          - called-late
                          - scheduled
                          - scheduled-late
                          - incomplete
                          - expired
                          - cancelled
                          - pending
                          - closed
                        startOn:
                          type: string
                          format: date
                        createdAt:
                          type: string
                          format: date-time
                        customerNotes:
                          type: string
                          minLength: 4
                          maxLength: 1024
                        notes:
                          type: string
                          minLength: 4
                          maxLength: 2048
                  page:
                    type: integer
                    format: int32
                    minimum: 1
                  totalCount:
                    type: integer
                    format: int32
                    minimum: 0
                additionalProperties: false
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
        default:
          description: unexpected error - need to finalize the error codes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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.
    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.
    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.
    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.
    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:
    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
    Referral:
      type: object
      description: A Referral tracks a patient being referred to a provider or facility for care, following the referral from creation through outreach, scheduling, and completion. It captures the referring and schedulable providers, status and status reason, scheduling window, and any related fax, upload, or appointment records used in referral management workflows.
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        name:
          type: string
        facility:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        provider:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        patient:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        referringProviderId:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        referringProvider:
          type: string
        duration:
          type: number
          format: int32
        statusReason:
          type: string
          enum:
          - patient-cancelled
          - invalid-insurance
          - missing-data
          - other
        statusReasonDescription:
          type: string
        source:
          type: string
          enum:
          - upload
          - patient-referral-form
          - ui
          - integrator
          - followup
          - manual
        status:
          type: string
          enum:
          - active
          - called
          - called-late
          - scheduled
          - scheduled-late
          - incomplete
          - expired
          - cancelled
          - pending
          - closed
        startOn:
          type: string
          format: date-time
        expireAt:
          type: string
          format: date-time
        attempt:
          type: number
          format: int32
        lastAttemptSentAt:
          type: string
          format: date-time
        calledAt:
          type: string
          format: date-time
        acceptedAt:
          type: string
          format: date-time
        scheduledAt:
          type: string
          format: date-time
        notes:
          type: string
        customerNotes:
          type: string
        appointmentType:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        reason:
          type: string
        departmentOrFacility:
          type: string
        scheduledByAppointment:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        scheduledByOffer:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        processedReferralFollowup:
          type: string
          enum:
          - pending
          - skipped
          - failed
          - success
        upload:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        faxUpload:
          type: string
          pattern: '[0-9a-f]'
          minLength: 24
          maxLength: 24
        faxSentAt:
          type: string
          format: date-time
        scheduleStartOn:
          type: string
          format: date-time
        referringProviderFaxNumberOverride:
          type: string
    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
    pageParam:
      in: query
      name: page
      required: false
      type: integer
      format: int32
      default: 1
      minimum: 1
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    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.
    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.
    RolesByUser:
      type: object
      description: Object containing 2 keys, referringProvider and renderingProvider. The value for each key is an array. The content of the array should be the root account ids under the same organization, where this user has the role with the same name of the key.
      required: []
      properties:
        referringProvider:
          type: array
          description: List of root account IDs under an organization where the user has the role referringProvider
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
        renderingProvider:
          type: array
          description: List of root account IDs under an organization where the user has the role renderingProvider
          items:
            type: string
            pattern: '[0-9a-f]'
            minLength: 24
            maxLength: 24
    SalesforceData:
      type: object
      description: Salesforce internal meta data for this account.
      required:
      - respectProvisioning
      properties:
        customerSuccessManager:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
            phone:
              type: string
        provisioning:
          type: array
          items:
            type: string
            enum:
            - reminder
            - waitlist
            - feedback
            - followup
            - referral
            - outbound-referral
            - chat
            - scheduler
            - recall
            - insurance
            - broadcast
            - form
            - intake-form
            - prequal-form
            - branding
            - upload
            - telehealth
            - waiting-room
            - luma-pay
            - insurance-verification
        respectProvisioning:
          type: boolean
          default: true
        lifeline:
          type: string
          enum:
          - trial
          - converted
          - active
          - churn
        mrr:
          type: number
        arr:
          type: number
        renewalDate:
          type: string
          format: date-time
        providers:
          type: number
        specialty:
          type: string
        referralTrialLimit:
          type: number
        recordType:
          type: string
        domesticAccessRequired:
          type: boolean
        goLiveAt:
          type: string
          format: date-time
        fullyImplementedAt:
          type: string
          format: date-time
        contractSignedAt:
          type: string
          format: date-time
        contractLength:
          type: number
        healthStatus:
          type: string
          default: green
          enum:
          - green
          - yellow
          - red
          - poor fit
          - Healthy
          - Neutral
          - Churn Risk
          - Advocate
        boardSegment:
          type: string
          default: Unknown
          enum:
          - Reseller
          - Strategic
          - Majors
          - Core
          - Sub 20
          - Unknown
        onboardingState:
          type: string
          default: Customer Success Introduction
          enum:
          - Customer Success Introduction
          - Kickoff
          - Integration
          - Discovery Call
          - Customization
          - Testing
          - Staff Training
          - Ready To Launch
          - Go-Live
          - Fully Implemented
        accountLifeline:
          type: string
          default: Active
          enum:
          - Unassigned
          - Assigned
          - Sales Accepted
          - Working
          - Sales Qualified
          - Open Opportunity
          - Nurture
          - Disqualified
          - Trial
          - Converted
          - Active
          - Churned
          - Partnered
          - Trial Ended (No Conversion)
    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
    Language:
      description: Language
      type: string
      enum:
      - ar
      - bn
      - cn
      - de
      - en
      - es
      - fa
      - fl
      - fr
      - gr
      - gu
      - hi
      - ht
      - hy
      - it
      - ja
      - km
      - ko
      - mr
      - my
      - pa
      - pl
      - pt
      - ru
      - so
      - th
      - ti
      - ur
      - vi
      - zh-t
      - zh
    PatientResponse:
      type: object
      description: A Patient represents an individual receiving care through a Luma Health customer's practice. It stores demographic and contact information, communication preferences and history, EHR sync identifiers, billing balances, and engagement stats used to power scheduling, messaging, and referral workflows.
      properties:
        _id:
          $ref: '#/components/schemas/idParam'
        user:
          $ref: '#/components/schemas/userParam'
        deleted:
          $ref: '#/components/schemas/deletedParam'
        createdBy:
          $ref: '#/components/schemas/createdByParam'
        updatedBy:
          $ref: '#/components/schemas/updatedByParam'
        createdAt:
          $ref: '#/components/schemas/createdAtParam'
        updatedAt:
          $ref: '#/components/schemas/updatedAtParam'
        culture:
          description: culture
          type: string
          enum:
          - cn
          - hk
        birthSex:
          description: birthSex
          type: string
          enum:
          - M
          - F
          - UNK
        race:
          description: race
          type: string
          enum:
          - american-indian-or-alaska-native
          - asian
          - black-or-african-american
          - native-hawaiian-or-other-pacific-islander
          - white
          - other-race
        ethnicityGroup:
          description: ethnicityGroup
          type: string
          enum:
          - hispanic-or-latino
          - not-hispanic-or-latino
        suffix:
          description: suffix
          type: string
          enum:
          - II
          - III
          - IV
          - Jr.
          - Sr.
        previousAddress:
          description: previousAddress
          type: string
        stats:
          type: object
          properties:
            counters:
              type: object
              properties:
                messagesSentToPatient:
                  description: stats.counters.messagesSentToPatient
                  type: number
                confirmedAppointments:
                  description: stats.counters.confirmedAppointments
                  type: number
                cancelledAppointments:
                  description: stats.counters.ca

# --- truncated at 32 KB (127 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/luma-health/refs/heads/main/openapi/luma-health-referrals-api-openapi.yml