LUlumahealth
engagements

Find or create an engagement

Finds an existing engagement matching the given criteria, or creates a new one if none exists. If patient is set and recipient is not, recipient and recipientType are automatically derived from patient.

post/engagements/findOrCreate

Request

Request body

patientstring required
direction'inbound' | 'outbound' required
agentsstring[]
channel'sms' | 'email' | 'voice' | 'chat' | 'whatsapp'
outboundNumberstring
expiresAtstring date-time
contextobject

Response

The found or newly created engagement

_idstring

Luma's internal ID of an object.

userstring

The ID of the root account user.

deleted0 | 1

Flag for logical deletion where 1 means deleted.

createdBystring

The ID of the user who created this object.

updatedBystring

The ID of the user who updated this object.

createdAtstring date-time

The date/time when this object was created.

updatedAtstring date-time

The date/time when this object was updated.

recipientstring

ID of the user this engagement is directed at.

recipientType'doctor' | 'staff' | 'patient' | 'system'

The kind of user recipient is.

patientstring

DEPRECATED. Use recipient and recipientType instead.

expiresAtstring date-time
topicstring
agentsstring[]

IDs of the AI agents involved in this engagement.

mainAgentstring

ID of the primary AI agent driving this engagement.

engagementSettingstring

ID of the EngagementSetting (voice/language preset) used for this engagement.

contextobject

Initial context provided to the engagement, used for outbound flows. Keys must correspond to AgentContextVariable names, and values must conform to that variable's schema.

completedAtstring date-time
type'conversational' | 'other'
status'in-progress' | 'failed' | 'success' | 'escalation_required' | 'idle'

Lifecycle status of the engagement. Transitions from in-progress to success, failed, or escalation_required.

statusReason'expired' | 'systemic_failure'

Changes

No recorded changes to this operation across all 6 revisions of this API.