> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.carewithemma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API: Trigger and Query Emma Workflows on Demand

> Use Emma's REST API to start patient workflows, initiate outbound calls, retrieve status, and perform scheduling actions 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.

```http theme={null}
Authorization: Bearer <your-api-key>
Content-Type: application/json
```

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

## Starting a workflow

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

```http theme={null}
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.

```json theme={null}
{
  "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.

```http theme={null}
GET /api/workflows/wf_9d3e...
Authorization: Bearer <your-api-key>
```

```json theme={null}
{
  "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.

<Tip>
  Keep Emma's permitted API actions scoped to the minimum needed for each workflow.
</Tip>

## When to use the REST API

<CardGroup cols={2}>
  <Card title="Use REST API when" icon="check">
    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.
  </Card>

  <Card title="Consider webhooks instead" icon="bell" href="/webhooks">
    Your system needs to notify Emma that something happened, rather than requesting an action. Webhooks are the right fit for event-driven triggers.
  </Card>
</CardGroup>