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

# Workflows API

> Instruct your Monumint agents to conduct work on leads

Workflows are routines that can be conducted by agents in Monumint. You can use the API to
start workflows on your leads. An agent conducts one workflow at a time on a given lead, so
over the lifetime of a lead an agent works through a sequence of them, one after another.

This guide walks the full experience: create a lead, determine which agent and workflow you
want to run, kick off the workflow on that lead, then hand the agent its next job once that
one finishes.

Four resources appear in this guide:

| Resource         | What it is                                                                        | Endpoints               |
| ---------------- | --------------------------------------------------------------------------------- | ----------------------- |
| **Agent**        | An AI worker that can communicate with leads                                      | `GET /api/v1/agents`    |
| **Workflow**     | A job that an agent can be tasked with conducting                                 | `GET /api/v1/workflows` |
| **Lead**         | The person or business that the agent is working with                             | `/api/v1/leads`         |
| **Workflow run** | One agent conducting one workflow on one lead. A lead accumulates these over time | `/api/v1/workflow-runs` |

## Before you start

1. **Generate an API key.** Visit [workspace settings](https://platform.getomni.ai/settings/api) to create an API key.
2. **Configure agents and workflows in the app.** Visit [agent settings](https://platform.getomni.ai/agents) to add and configure agents,
   and visit [workflow settings](https://platform.getomni.ai/workflows) to add and configure workflows.

All requests should be made to `https://api-v2.getomni.ai`. Use your workspace API key to authenticate
with the `x-api-key` header.

## 1. Create a lead

If you already create leads through the API or a CRM sync, you can reuse existing
leads and skip to step 2. To create a lead through the API:

**`POST /api/v1/leads`**

<CodeGroup>
  ```json title="Request" theme={null}
  {
    "firstName": "Jordan",
    "lastName": "Rivera",
    "businessName": "Pacific Coast Container Haulers",
    "email": "jordan@pacificcoast.example",
    "externalLeadId": "crm-4471"
  }
  ```

  ```json title="Response" theme={null}
  { "success": true, "lead": { "id": "b1f0…", "externalLeadId": "crm-4471" } }
  ```
</CodeGroup>

## 2. Identify your agents and workflows

Agents and workflows can be configured within the Monumint app. Once they are set up, you can
retrieve ids that identify each workflow and agent. To retrieve the agents configured in your workspace:

**`GET /api/v1/agents`**

<CodeGroup>
  ```json title="Response" theme={null}
  {
    "success": true,
    "agents": [
      {
        "id": "7c9e…",
        "name": "Sam",
        "email": "sam@pacificbank.getomni.ai",
        "phoneNumber": "+14155550142",
        "createdAt": "2026-03-02T15:20:11.000Z",
        "updatedAt": "2026-08-14T09:02:45.000Z"
      }
    ]
  }
  ```
</CodeGroup>

To retrieve the workflows configured in your workspace:

**`GET /api/v1/workflows`**

<CodeGroup>
  ```json title="Response" theme={null}
  {
    "success": true,
    "workflows": [
      {
        "id": "3fa8…",
        "name": "Document collection",
        "type": "CHECKLIST",
        "createdAt": "2026-03-02T15:21:40.000Z",
        "updatedAt": "2026-06-11T11:45:02.000Z"
      },
      {
        "id": "9b21…",
        "name": "Borrower questions",
        "type": "SUPPORT",
        "createdAt": "2026-04-18T10:06:33.000Z",
        "updatedAt": "2026-07-29T16:12:50.000Z"
      }
    ]
  }
  ```
</CodeGroup>

Each workflow has a `type` that defines what work actually gets performed:

| Type        | Behavior                                             |
| ----------- | ---------------------------------------------------- |
| `CHECKLIST` | Collect information and documents from the lead      |
| `REMINDER`  | Send a recurring message to a lead on a set schedule |
| `SUPPORT`   | Answer any inbound questions from the lead           |

## 3. Create the workflow run

Up until this point, we've configured agents and workflows, and we've created leads in Monumint, but no work is actually being performed.
To tell an agent to start conducting a workflow on a particular lead, we need to create a workflow run:

**`POST /api/v1/workflow-runs`**

<CodeGroup>
  ```json title="Request" theme={null}
  {
    "leadId": "b1f0…",
    "agentId": "7c9e…",
    "workflowId": "3fa8…"
  }
  ```

  ```json title="Response" theme={null}
  {
    "success": true,
    "workflowRun": {
      "id": "5d8c…",
      "leadId": "b1f0…",
      "agentId": "7c9e…",
      "workflowId": "3fa8…",
      "status": "ACTIVE",
      "createdAt": "2026-09-10T17:42:03.000Z",
      "completedAt": null,
      "cancelledAt": null
    }
  }
  ```
</CodeGroup>

Depending on the workflow's type, the agent may begin to send messages to the lead over text, email, and other channels.
At this point, you should store `workflowRun.id` for use with the additional endpoints and webhooks described below.

## 4. Subscribe to events

Monumint dispatches webhook events so that you can stay informed of activity tied to a workflow run. You can register to receive workflow run events with
[Create Webhook](/api-reference/webhooks/create-webhook):

**`POST /api/v1/webhooks`**

<CodeGroup>
  ```json title="Request" theme={null}
  {
    "url": "https://your-app.example/webhooks/monumint",
    "events": [
      "workflow_run.started",
      "workflow_run.paused",
      "workflow_run.resumed",
      "workflow_run.completed",
      "workflow_run.cancelled"
    ],
    "headers": { "x-shared-secret": "choose-a-random-value" }
  }
  ```
</CodeGroup>

The events which pertain to workflow runs are:

| Event                                                                             | Fires when                                      |
| --------------------------------------------------------------------------------- | ----------------------------------------------- |
| [`workflow_run.started`](/api-reference/webhooks/events/workflow-run-started)     | A workflow run is created                       |
| [`workflow_run.paused`](/api-reference/webhooks/events/workflow-run-paused)       | A workflow run is paused                        |
| [`workflow_run.resumed`](/api-reference/webhooks/events/workflow-run-resumed)     | A paused workflow run is resumed                |
| [`workflow_run.completed`](/api-reference/webhooks/events/workflow-run-completed) | The agent has finished conducting this workflow |
| [`workflow_run.cancelled`](/api-reference/webhooks/events/workflow-run-cancelled) | A workflow run is stopped prior to completion   |

Each event carries the workflow run under `workflowRun` — the same object the
endpoints above return — alongside the workspace, the lead, and your own
`externalLeadId`:

```json title="Event payload" theme={null}
{
  "event": "workflow_run.started",
  "actor": null,
  "occurredAt": "2026-09-10T17:42:03.000Z",
  "workspaceId": "6048…",
  "leadId": "b1f0…",
  "externalLeadId": "crm-4471",
  "workflowRun": {
    "id": "5d8c…",
    "leadId": "b1f0…",
    "agentId": "7c9e…",
    "workflowId": "3fa8…",
    "status": "ACTIVE",
    "createdAt": "2026-09-10T17:42:03.000Z",
    "completedAt": null,
    "cancelledAt": null
  }
}
```

See [Webhook Events](/api-reference/webhooks/webhook-events) for a complete reference of every
event and its payload.

## 5. Create another workflow run

An agent generally conducts one workflow at a time on a given lead. But once that workflow finishes, you can
tell the agent to perform another job on that lead by calling the workflow run creation endpoint again,
usually with a different workflow id:

**`POST /api/v1/workflow-runs`**

<CodeGroup>
  ```json title="Request" theme={null}
  {
    "leadId": "b1f0…",
    "agentId": "7c9e…",
    "workflowId": "9b21…"
  }
  ```

  ```json title="Response" theme={null}
  {
    "success": true,
    "workflowRun": {
      "id": "e4a7…",
      "leadId": "b1f0…",
      "agentId": "7c9e…",
      "workflowId": "9b21…",
      "status": "ACTIVE",
      "createdAt": "2026-09-10T18:00:04.000Z",
      "completedAt": null,
      "cancelledAt": null
    }
  }
  ```
</CodeGroup>

If you create a workflow run while the agent is still conducting one on the same lead, the
request is rejected with `409 Agent is already linked to this lead`. Wait for the agent to
finish, or cancel the current workflow run first.

## 6. Manage the workflow run

Once a workflow run exists, you may wish to control it through various operations.
Each is a `POST` with no body, and returns the workflow run in its new state.

| Operation    | Endpoint                                              | What happens                                                                                 |
| ------------ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Pause**    | `POST /api/v1/workflow-runs/{workflowRunId}/pause`    | The agent will stop conducting this workflow                                                 |
| **Resume**   | `POST /api/v1/workflow-runs/{workflowRunId}/resume`   | The agent will resume conducting this workflow                                               |
| **Cancel**   | `POST /api/v1/workflow-runs/{workflowRunId}/cancel`   | The agent will permanently cease conducting this workflow                                    |
| **Complete** | `POST /api/v1/workflow-runs/{workflowRunId}/complete` | Immediately consider the workflow complete, even if the agent was still conducting this work |

Each of these acts on a single workflow run rather than on the agent or the lead. Cancelling
one frees the agent to take on its next job for that lead.

## 7. Monitor workflow runs

In addition to staying apprised of workflow run activity using the events described above, you can also
use the following endpoints to check the current state of workflow runs. To read one workflow run:

**`GET /api/v1/workflow-runs/{workflowRunId}`**

<CodeGroup>
  ```json title="Response" theme={null}
  {
    "success": true,
    "workflowRun": {
      "id": "5d8c…",
      "leadId": "b1f0…",
      "agentId": "7c9e…",
      "workflowId": "3fa8…",
      "status": "ACTIVE",
      "createdAt": "2026-09-10T17:42:03.000Z",
      "completedAt": null,
      "cancelledAt": null
    }
  }
  ```
</CodeGroup>

Or to list all workflow runs for a lead:

**`GET /api/v1/workflow-runs?leadId={leadId}`**

<CodeGroup>
  ```json title="Response" theme={null}
  {
    "success": true,
    "workflowRuns": [
      {
        "id": "e4a7…",
        "leadId": "b1f0…",
        "agentId": "7c9e…",
        "workflowId": "9b21…",
        "status": "ACTIVE",
        "createdAt": "2026-09-10T18:00:04.000Z",
        "completedAt": null,
        "cancelledAt": null
      },
      {
        "id": "5d8c…",
        "leadId": "b1f0…",
        "agentId": "7c9e…",
        "workflowId": "3fa8…",
        "status": "COMPLETED",
        "createdAt": "2026-09-10T17:42:03.000Z",
        "completedAt": "2026-09-10T18:00:00.000Z",
        "cancelledAt": null
      }
    ]
  }
  ```
</CodeGroup>

Workflow runs are returned newest first, so this is the lead's work history: what the agent is
conducting now, and everything it has already finished.

## 8. Wrapping up with a lead

In the lifespan of a lead, you may ask your agents to perform multiple workflows.
A lead can remain active in your system even if no work is actively being conducted on it.

For leads that you consider fully complete, you can mark the lead as completed to wrap up
their entire record:

**`PUT /api/v1/leads`**

<CodeGroup>
  ```json title="Request" theme={null}
  { "leadId": "b1f0…", "status": "COMPLETED" }
  ```
</CodeGroup>

## 9. Putting it all together

The script below wires the whole guide together: it creates a lead, looks up the agent
and workflow to use, subscribes to the events, puts the agent to work, and reads the
result back. It uses [`jq`](https://jqlang.github.io/jq/) to pull ids out of each response.

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

API_URL="https://api-v2.getomni.ai"
API_KEY="sk-..."

auth=(-H "x-api-key: $API_KEY" -H "Content-Type: application/json")

# Create a lead. Skip this if the lead already exists in Monumint.
LEAD_ID=$(curl -sS -X POST "$API_URL/api/v1/leads" "${auth[@]}" \
  -d '{
    "firstName": "Jordan",
    "lastName": "Rivera",
    "businessName": "Pacific Coast Container Haulers",
    "email": "jordan@pacificcoast.example",
    "externalLeadId": "crm-4471"
  }' | jq -r '.lead.id')

# Look up the agent and the workflow you want that agent to conduct.
AGENT_ID=$(curl -sS "$API_URL/api/v1/agents" "${auth[@]}" \
  | jq -r '.agents[] | select(.name == "Sam") | .id')

WORKFLOW_ID=$(curl -sS "$API_URL/api/v1/workflows" "${auth[@]}" \
  | jq -r '.workflows[] | select(.name == "Document collection") | .id')

# Subscribe to the workflow run events. This is one-time setup for your
# workspace rather than something to repeat per lead.
curl -sS -X POST "$API_URL/api/v1/webhooks" "${auth[@]}" \
  -d '{
    "url": "https://your-app.example/webhooks/monumint",
    "events": [
      "workflow_run.started",
      "workflow_run.paused",
      "workflow_run.resumed",
      "workflow_run.completed",
      "workflow_run.cancelled"
    ],
    "headers": { "x-shared-secret": "choose-a-random-value" }
  }' > /dev/null

# Put the agent to work on the lead.
WORKFLOW_RUN_ID=$(curl -sS -X POST "$API_URL/api/v1/workflow-runs" "${auth[@]}" \
  -d "{
    \"leadId\": \"$LEAD_ID\",
    \"agentId\": \"$AGENT_ID\",
    \"workflowId\": \"$WORKFLOW_ID\"
  }" | jq -r '.workflowRun.id')

echo "Workflow run $WORKFLOW_RUN_ID is now conducting work on lead $LEAD_ID"

# Read the current state of that work at any point.
curl -sS "$API_URL/api/v1/workflow-runs/$WORKFLOW_RUN_ID" "${auth[@]}" | jq

# When this workflow completes, Monumint sends workflow_run.completed. Your
# webhook handler creates the next workflow run for the same lead and agent,
# as described in step 5.

# Pause it, then resume it.
curl -sS -X POST "$API_URL/api/v1/workflow-runs/$WORKFLOW_RUN_ID/pause" "${auth[@]}" | jq
curl -sS -X POST "$API_URL/api/v1/workflow-runs/$WORKFLOW_RUN_ID/resume" "${auth[@]}" | jq

# Once you're done with the lead entirely, wrap up its record.
curl -sS -X PUT "$API_URL/api/v1/leads" "${auth[@]}" \
  -d "{ \"leadId\": \"$LEAD_ID\", \"status\": \"COMPLETED\" }" | jq
```