Workflows API

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

Generate an API key. Visit workspace settings to create an API key.
Configure agents and workflows in the app. Visit agent settings to add and configure agents, and visit workflow settings 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

{
  "firstName": "Jordan",
  "lastName": "Rivera",
  "businessName": "Pacific Coast Container Haulers",
  "email": "jordan@pacificcoast.example",
  "externalLeadId": "crm-4471"
}

{ "success": true, "lead": { "id": "b1f0…", "externalLeadId": "crm-4471" } }

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

{
  "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"
    }
  ]
}

To retrieve the workflows configured in your workspace: GET /api/v1/workflows

{
  "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"
    }
  ]
}

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

{
  "leadId": "b1f0…",
  "agentId": "7c9e…",
  "workflowId": "3fa8…"
}

{
  "success": true,
  "workflowRun": {
    "id": "5d8c…",
    "leadId": "b1f0…",
    "agentId": "7c9e…",
    "workflowId": "3fa8…",
    "status": "ACTIVE",
    "createdAt": "2026-09-10T17:42:03.000Z",
    "completedAt": null,
    "cancelledAt": null
  }
}

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. 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: POST /api/v1/webhooks

{
  "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" }
}

The events which pertain to workflow runs are:

Event	Fires when
`workflow_run.started`	A workflow run is created
`workflow_run.paused`	A workflow run is paused
`workflow_run.resumed`	A paused workflow run is resumed
`workflow_run.completed`	The agent has finished conducting this workflow
`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:

Event payload

{
  "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 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

{
  "leadId": "b1f0…",
  "agentId": "7c9e…",
  "workflowId": "9b21…"
}

{
  "success": true,
  "workflowRun": {
    "id": "e4a7…",
    "leadId": "b1f0…",
    "agentId": "7c9e…",
    "workflowId": "9b21…",
    "status": "ACTIVE",
    "createdAt": "2026-09-10T18:00:04.000Z",
    "completedAt": null,
    "cancelledAt": null
  }
}

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}

{
  "success": true,
  "workflowRun": {
    "id": "5d8c…",
    "leadId": "b1f0…",
    "agentId": "7c9e…",
    "workflowId": "3fa8…",
    "status": "ACTIVE",
    "createdAt": "2026-09-10T17:42:03.000Z",
    "completedAt": null,
    "cancelledAt": null
  }
}

Or to list all workflow runs for a lead: GET /api/v1/workflow-runs?leadId={leadId}

{
  "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
    }
  ]
}

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

{ "leadId": "b1f0…", "status": "COMPLETED" }

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 to pull ids out of each response.

#!/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

Getting Started

Use Cases

Leads

AI Agent

Configuration

White-Label Portal

Before you start

1. Create a lead

2. Identify your agents and workflows

3. Create the workflow run

5. Create another workflow run

6. Manage the workflow run

7. Monitor workflow runs

8. Wrapping up with a lead

9. Putting it all together

​Before you start

​1. Create a lead

​2. Identify your agents and workflows

​3. Create the workflow run

​4. Subscribe to events

​5. Create another workflow run

​6. Manage the workflow run

​7. Monitor workflow runs

​8. Wrapping up with a lead

​9. Putting it all together

Before you start

1. Create a lead

2. Identify your agents and workflows

3. Create the workflow run

4. Subscribe to events

5. Create another workflow run

6. Manage the workflow run

7. Monitor workflow runs

8. Wrapping up with a lead

9. Putting it all together