Create Workflow Run

Start an agent conducting a workflow on a lead

POST /api/v1/workflow-runs

Node.js

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));

201

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

Create a workflow run: one agent conducting one workflow on one lead. Get the agentId from List Agents and the workflowId from List Workflows.

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 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.

Node.js

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));

201

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