Luma Health Referrals API
Inbound and outbound referral management across the care network.
OpenAPI Specification
openapi: 3.0.0
info:
version: 2.0.0
title: Rest-Service
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
components:
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
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.
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.
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.
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.
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.
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
AppointmentTypeResponse:
type: object
description: >-
An Appointment Type defines a category of visit that a provider or
facility offers, such as a routine office visit or a telehealth consult,
along with its default duration, visibility, and optional patient intake
forms (checklist). It can also declare dependent appointment types and
matching rules used to determine facility or availability logic when a
related follow-up appointment needs to be scheduled.
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
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
alternativeName:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
description:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
duration:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
externalId:
$ref: '#/components/schemas/ExternalId'
visible:
type: integer
format: int32
default: 15
dependents:
type: array
items:
type: object
properties:
appointmentType:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
rules:
type: object
properties:
findAvailabilityAfter:
type: object
properties:
enabled:
type: boolean
default: true
maxMinutes:
type: number
default: 30
minMinutes:
type: number
facilityMatch:
type: object
properties:
criteria:
type: string
enum:
- _id
- postcode
AppointmentTypeRequestUpdate:
type: object
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
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
alternativeName:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
description:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
duration:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
externalId:
$ref: '#/components/schemas/ExternalId'
visible:
type: integer
format: int32
default: 15
dependents:
type: array
items:
type: object
properties:
appointmentType:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
rules:
type: object
properties:
findAvailabilityAfter:
type: object
properties:
enabled:
type: boolean
default: true
maxMinutes:
type: number
default: 30
minMinutes:
type: number
facilityMatch:
type: object
properties:
criteria:
type: string
enum:
- _id
- postcode
AppointmentTypeRequestCreate:
type: object
required:
- name
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
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
alternativeName:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
description:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
duration:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
externalId:
$ref: '#/components/schemas/ExternalId'
visible:
type: integer
format: int32
default: 15
dependents:
type: array
items:
type: object
properties:
appointmentType:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
rules:
type: object
properties:
findAvailabilityAfter:
type: object
properties:
enabled:
type: boolean
default: true
maxMinutes:
type: number
default: 30
minMinutes:
type: number
facilityMatch:
type: object
properties:
criteria:
type: string
enum:
- _id
- postcode
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
Appointment:
type: object
description: >-
An Appointment represents a scheduled visit between a patient and a
provider at a facility, including the date, duration, appointment type,
and status (unconfirmed, confirmed, or cancelled). It tracks how the
appointment was created or updated, for example through an EHR
integration sync, the scheduling UI, telehealth, or a patient
rescheduling via text, and is the core object driving Luma Health's
scheduling, reminders, and check-in 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'
patient:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
provider:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
facility:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
type:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
date:
type: string
format: date-time
duration:
type: integer
format: int32
default: 15
source:
type: string
enum:
- integrator
- reminder
- ui
- waitlist
- reschedule
- telehealth
status:
type: string
enum:
- unconfirmed
- confirmed
- cancelled
AssistantTransferRulesBulkRequest:
type: object
required:
- entries
properties:
entries:
type: array
description: Array of transfer rule entries to create
minItems: 1
items:
type: object
required:
- assistants
- name
- transferNumber
- type
properties:
assistants:
type: array
description: Array of assistant IDs for this entry
minItems: 1
items:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
name:
type: string
description: Name of the transfer rule (used for intent routing)
minLength: 1
metadata:
type: object
description: Additional metadata
properties:
city:
type: string
description: City where the department is located
state:
type: string
description: State where the department is located
zip:
type: string
description: ZIP code for the department location
address:
type: string
description: Street address of the department
suiteBuildingRoom:
type: string
description: Suite, building, or room number
specialty:
type: string
description: Medical specialty of the department
action:
type: string
description: Action associated with the department
enabled:
type: boolean
description: Whether the transfer rule is enabled
default: false
type:
type: string
description: Type of transfer rule
enum:
- intent_routing
- rule_based
assistantNumbers:
type: array
description: Array of outbound number IDs
items:
type: string
transferNumber:
type: string
description: Phone number to transfer calls to
transferMessage:
type: string
description: Message played when transferring
transferFailedMessage:
type: string
description: Message played when transfer fails
afterHoursEndCallMessage:
type: string
description: Message played when office is closed
timezone:
type: string
description: Timezone for working hours (e.g., America/Los_Angeles)
textPatientBackInHub:
type: object
description: Configuration for texting patient back
properties:
enabled:
type: boolean
description: Whether text-back feature is enabled
minutesBeforeClosingTime:
type: integer
description: Minutes before closing to offer text-back option
minimum: 0
textPatientBackConfirmationSentMessage:
type: string
description: Confirmation message sent when text-back is requested
hubSmsTextPatientBackConfirmationSentMessage:
type: string
description: SMS confirmation message sent via hub
offerToTransferMessage:
type: string
description: Message offering to transfer the caller
offerToTextBackOrTransferMessage:
type: string
description: Message offering text-back or transfer options
offerToTextBackOrEndCallMessage:
type: string
description: Message offering text-back or end call options
officeClosedTransferNotAvailableOfferToTextBackMessage:
type: string
description: Message when office is closed and transfer unavailable
officeNearClosingTimeTransferNotAdvisedOfferToTextBackMessage:
type: string
description: Message when office is near closing time
workingHours:
type: array
description: Working hours configuration for each day of the week
items:
type: object
required:
- earliest
- latest
- dayOfWeek
properties:
earliest:
type: object
description: Start time for the day
required:
- hour
- minute
properties:
hour:
type: integer
minimum: 0
maximum: 23
minute:
type: integer
minimum: 0
maximum: 59
latest:
type: object
description: End time for the day
required:
- hour
- minute
properties:
hour:
type: integer
minimum: 0
maximum: 23
minute:
type: integer
minimum: 0
maximum: 59
dayOfWeek:
type: integer
description: Day of week (0=Sunday, 6=Saturday)
minimum: 0
maximum: 6
replaceAll:
type: boolean
description: Whether to replace all existing entries in the intent routing table
default: false
AssistantTransferRulesResponse:
type: object
description: >-
Represents the call routing configuration for a Navigator AI assistant,
defining which assistant or phone numbers it applies to, the number and
message to use when transferring a caller to staff, and business hours
used to decide whether to offer a transfer, an SMS follow up, or an
after-hours message instead. It drives how an automated phone assistant
decides when and where to hand a call off to a human.
properties:
_id:
type: string
description: Unique identifier in Luma's database
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
user:
type: string
description: Organization ID
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
deleted:
type: integer
description: Soft delete timestamp (0 if not deleted)
default: 0
createdBy:
type: string
description: ID of user who created this record
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
updatedBy:
type: string
description: ID of user who last updated this record
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
createdAt:
type: string
format: date-time
description: Timestamp when record was created
updatedAt:
type: string
format: date-time
description: Timestamp when record was last updated
name:
type: string
description: Name of the transfer rule (used for intent routing)
metadata:
type: object
description: Additional metadata
properties:
city:
type: string
description: City where the department is located
state:
type: string
description: State where the department is located
zip:
type: string
description: ZIP code for the department location
address:
type: string
description: Street address of the department
suiteBuildingRoom:
type: string
description: Suite, building, or room number
specialty:
type: string
description: Medical specialty of the department
action:
type: string
description: Action associated with the department
enabled:
type: boolean
description: Whether the transfer rule is enabled
default: false
type:
type: string
description: Type of transfer rule
enum:
- intent_routing
- rule_based
assistants:
type: array
description: Array of assistant IDs
items:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
assistantNumbers:
type: array
description: Array of outbound number IDs
items:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
transferNumber:
type: string
description: Phone number to transfer calls to
transferMessage:
type: string
description: Message played when transferring
default: Transferring you to a staff.
transferFailedMessage:
type: string
description: Message played when transfer fails
default: >-
Unfortunately the transfer has failed. Sorry please try calling
again.
afterHoursEndCallMessage:
type: string
description: Message played when office is closed
default: >-
Unfortunately, the office is closed. Please call back during normal
business hours. Goodbye
timezone:
type: string
description: Timezone for working hours
default: America/Los_Angeles
textPatientBackInHub:
type: object
description: Configuration for texting patient back
properties:
enabled:
type: boolean
description: Whether text-back feature is enabled
default: false
minutesBeforeClosingTime:
type: integer
description: Minutes before closing to offer text-back option
default: 30
textPatientBackConfirmationSentMessage:
type: string
description: Confirmation message sent when text-back is requested
default: >-
I've sent you an SMS confirming this request. Our team will text you
back via the number you have provided.
hubSmsTextPatientBackConfirmationSentMessage:
type: string
description: SMS confirmation message sent via hub
default: >-
Thank you for your message. We will get back to you as soon as
possible.
offerToTransferMessage:
type: string
description: Message offering to transfer the caller
default: Would you like to be transferred to a staff member?
offerToTextBackOrTransferMessage:
type: string
description: Message offering text-back or transfer options
default: >-
Would you like to receive a text message or be transferred to a
staff member?
offerToTextBackOrEndCallMessage:
type: string
description: Message offering text-back or end call options
default: Would you like to receive a text message or end the call?
officeClosedTransferNotAvailableOfferToTextBackMessage:
type: string
description: Message when office is closed and transfer unavailable
default: >-
Unfortunately, the office is closed. Would you like to leave a
message and a staff member will reach back in the next business day?
officeNearClosingTimeTransferNotAdvisedOfferToTextBackMessage:
type: string
description: Message when office is near closing time
default: >-
The office is closing soon. If you choose to be transferred to a
Staff, there is a chance that your call won't be answered. Would you
like to leave a message and a staff member will reach you as soon as
possible?
workingHours:
type: array
description: Working hours configuration for each day of the week
items:
type: object
properties:
earliest:
type: object
description: Start time for the day
properties:
hour:
type: integer
minimum: 0
maximum: 23
minute:
type: integer
minimum: 0
maximum: 59
latest:
type: object
description: End time for the day
properties:
hour:
type: integer
minimum: 0
maximum: 23
minute:
type: integer
minimum: 0
maximum: 59
dayOfWeek:
type: integer
description: Day of week (0=Sunday, 6=Saturday)
minimum: 0
maximum: 6
AssistantInstanceResponse:
type: object
description: >-
An AssistantInstance represents a single conversation between Luma's
Navigator AI assistant and a patient (or staff member), spanning one or
more channels such as a voice call, SMS, or chat. It tracks the
lifecycle of that conversation as it moves from idle to in-progress to a
terminal success or failure status, whether the patient's identity was
verified, which entry points were used, and reporting data about the
call's outcome and detected intents. AssistantActions attach to an
AssistantInstance as the individual tool calls made during the
conversation.
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'
release:
type: string
description: Which release track of the assistant handled this conversation.
default: current
enum:
- current
- next
- preProd
patient:
type: string
description: ID of the patient in this conversation.
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
verified:
type: boolean
description: Whether the patient's identity has been confirmed.
default: false
onBehalfOf:
type: string
description: >-
ID of the patient being discussed, when different from `patient`
(for example, a guardian calling about a dependent).
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
status:
type: string
description: Lifecycle status of the conversation.
default: idle
enum:
- idle
- in-progress
- failure
- success
statusUpdatedAt:
type: string
format: date-time
description: When `status` was last updated.
statusReason:
type: string
description: Why the conversation reached its terminal status.
enum:
- success-by-assistant
- success-by-transfer
- success-by-patient
- success-by-staff
- success-by-assistant-timeout
- failure-by-assistant
- failure-by-patient
- failure-by-staff
- incomplete-success-criteria
- timed-out
- no-new-messages
- maximum-retries
assistant:
type: string
description: ID of the Assistant configuration driving this conversation.
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
entryPoints:
type: array
description: The channels used to reach the assistant during this conversation.
items:
type: object
properties:
channel:
type: string
enum:
- sms
- email
- voice
- inapp
- chat
- fax
- whatsapp
- rcs
- lumabot
- internal
lastMessageAt:
type: string
format: date-time
direction:
type: string
enum:
- inbound
- outbound
startedAt:
type: string
format: date-time
finishedAt:
type: string
format: date-time
duration:
typ
# --- truncated at 32 KB (1015 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/luma-health/refs/heads/main/openapi/luma-health-openapi.yaml