REST API: Trigger and Query Emma Workflows on Demand

Emma’s REST API lets your systems start workflows and retrieve results on demand. A client application sends a structured request and Emma executes the workflow — initiating a patient call, scheduling an appointment, or returning a status summary. Emma can also call your APIs during a workflow when it needs to retrieve context or perform an approved action in your system.

Common actions

Action	Description
Start an outbound patient call	Initiate a voice call to a patient and begin a configured workflow
Trigger an abandonment recovery workflow	Start the recovery sequence for a dropped-off patient
Retrieve appointment availability	Get open slots from a connected scheduling system
Schedule or reschedule an appointment	Book or move an appointment in the EMR
Create or update a patient record	Write registration or update data to the EMR
Retrieve workflow or interaction status	Get the current state and outcome of a running or completed workflow

Authentication

Every request must include your Emma API key in the Authorization header.

Authorization: Bearer <your-api-key>
Content-Type: application/json

Your API key is available on the Emma Integrations page. Treat it as a secret and never expose it in client-side code.

Starting a workflow

The example below starts an outbound call to a patient as part of an abandonment recovery workflow.

POST /api/workflows/start
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "workflowType": "abandonment-recovery",
  "clinicId": "clinic_abc123",
  "patient": {
    "firstName": "Jordan",
    "lastName": "Lee",
    "phone": "+15551234567"
  },
  "context": {
    "sessionId": "sess_8f2c...",
    "resumeUrl": "https://your-platform.example/resume/sess_8f2c..."
  }
}

Emma responds immediately with a workflow ID and initial status that you can use to track progress.

{
  "workflowId": "wf_9d3e...",
  "status": "started",
  "patientFirstName": "Jordan",
  "patientLastName": "Lee"
}

Retrieving workflow status

Use the workflow ID returned at creation to poll for the current state and final outcome.

GET /api/workflows/wf_9d3e...
Authorization: Bearer <your-api-key>

{
  "workflowId": "wf_9d3e...",
  "status": "completed",
  "outcome": "RECOVERED",
  "completedAt": "2026-09-24T14:27:41Z"
}

Emma calling your APIs

Emma can also call your APIs during a live workflow when it needs to retrieve data or perform an approved action — such as checking appointment availability or updating a patient record. You configure the endpoint, authentication method, and permitted actions in the Emma Integrations settings. Emma will only call endpoints and perform actions you have explicitly approved.

Keep Emma’s permitted API actions scoped to the minimum needed for each workflow.

When to use the REST API

Use REST API when

An action must happen on demand, you need a defined request/response contract, or you want to retrieve the current state and outcome of a running or completed workflow.

Consider webhooks instead

Your system needs to notify Emma that something happened, rather than requesting an action. Webhooks are the right fit for event-driven triggers.

Overview

Integration Methods

Workflow Guides

REST API: Trigger and Query Emma Workflows on Demand

Common actions

Authentication

Starting a workflow

Retrieving workflow status

Emma calling your APIs

When to use the REST API

Use REST API when

Consider webhooks instead

​Common actions

​Authentication

​Starting a workflow

​Retrieving workflow status

​Emma calling your APIs

​When to use the REST API

Use REST API when

Consider webhooks instead

Common actions

Authentication

Starting a workflow

Retrieving workflow status

Emma calling your APIs

When to use the REST API