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

# Create Workflow Run

> Start an agent conducting a workflow on a lead

Create a workflow run: one agent conducting one workflow on one lead. Get the `agentId` from [List Agents](https://docs.monumint.com/api-reference/agents/list-agents.md) and the `workflowId` from [List Workflows](https://docs.monumint.com/api-reference/workflows/list-workflows.md).

Depending on the workflow's type, the agent may begin sending messages to the lead.

## Authentication

Requires the `x-api-key` header with a valid workspace API key.

## Body Parameters

**leadId** `string` *required*

The lead the workflow is conducted on.

**agentId** `string` *required*

The agent that conducts the workflow.

**workflowId** `string` *required*

The workflow the agent conducts.

**portalUrl** `string`

A portal URL for this run. When set, this link is sent to the lead instead of
the lead’s existing portal link or the workflow’s portal URL template. Must be
a valid URL.

**externalId** `string`

An identifier for this run in your own system (e.g. from a CRM). It is
returned on the run and carried inside `workflowRun` on every
`workflow_run.*` webhook, so you can match events to your own records before
you have stored our id. It does not have to be unique: several runs may share
one, for example when you start a new run for the same record after an
earlier one was cancelled. At most 255 characters.

No other fields are accepted.

## Response

**success** `boolean`

Whether the request succeeded.

**workflowRun** `object`

The new workflow run. See [Get Workflow
Run](https://docs.monumint.com/api-reference/workflow-runs/get-workflow-run.md) for the full shape. A new
workflow run is always `ACTIVE`.

## Errors

**400** `error`

`leadId`, `agentId`, or `workflowId` is missing, or the body carries an
unrecognized field.

**404** `error`

The `leadId`, `agentId`, or `workflowId` isn't in your workspace.

**409** `error`

The workflow run cannot be created:

* **`Agent is already linked to this lead`**: this agent already has an open
  (`ACTIVE` or `PAUSED`) workflow run on this lead. Cancel or complete it first, or
  use a different agent.
* **`… already collects this lead's checklist`**: a lead can have only one
  open `CHECKLIST` workflow run at a time.
* **`This reminder workflow has no schedule configured yet`**: the
  `REMINDER` workflow needs a schedule set in the Monumint app first.

```javascript Node.js theme={null}
const options = {
  method: "POST",
  headers: {
    "x-api-key": "<your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    leadId: "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
    agentId: "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    workflowId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  }),
};

fetch("https://api-v2.getomni.ai/api/v1/workflow-runs", options)
  .then((response) => response.json())
  .then((response) => console.log(response))
  .catch((err) => console.error(err));
```

```python Python theme={null}
import requests

url = "https://api-v2.getomni.ai/api/v1/workflow-runs"
headers = {"x-api-key": "<your-api-key>", "Content-Type": "application/json"}
payload = {
    "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
    "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
}

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())
```

```bash cURL theme={null}
curl --request POST \
  --url https://api-v2.getomni.ai/api/v1/workflow-runs \
  --header 'x-api-key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
    "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'
```

```json 201 theme={null}
{
  "success": true,
  "workflowRun": {
    "id": "5d8c1b2a-3e4f-5061-7283-94a5b6c7d8e9",
    "leadId": "b1f0a790-201b-47e9-84ed-cc7eed1270c5",
    "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "portalUrl": null,
    "externalId": null,
    "status": "ACTIVE",
    "createdAt": "2026-09-10T17:42:03.000Z",
    "completedAt": null,
    "cancelledAt": null
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.