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

# Workflows

> Create, manage, run, schedule, and monitor workflows.

# Workflows

Workflows let you orchestrate actions and call flows for your organization.

## Authentication & scope

* Header: `X-API-Key: YOUR_API_KEY`
* Read operations: `workflows:read`
* Write operations: `workflows:write`
* Use **API Reference** for Try-it on every workflow endpoint.

## `POST /v1/workflows`

Creates a workflow. Body is DTO-accurate to `CreateWorkflowDto`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.indigenius.ai/v1/workflows" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Lead follow-up",
      "callbackUrl": "https://client.example.com/hooks/workflow",
      "webhook": {
        "url": "https://client.example.com/hooks/workflow"
      },
      "endCall": {
        "phrases": ["goodbye", "end call"]
      }
    }'
  ```

  ```javascript Node theme={null}
  const response = await fetch('https://api.indigenius.ai/v1/workflows', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.INDIGENIUS_API_KEY,
    },
    body: JSON.stringify({
      title: 'Lead follow-up',
      callbackUrl: 'https://client.example.com/hooks/workflow',
      webhook: { url: 'https://client.example.com/hooks/workflow' },
      endCall: { phrases: ['goodbye', 'end call'] },
    }),
  });
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  payload = {
      "title": "Lead follow-up",
      "callbackUrl": "https://client.example.com/hooks/workflow",
      "webhook": {"url": "https://client.example.com/hooks/workflow"},
      "endCall": {"phrases": ["goodbye", "end call"]},
  }
  response = requests.post(
      "https://api.indigenius.ai/v1/workflows",
      headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json=payload,
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `201 Created`

```json theme={null}
{
  "status": true,
  "message": "Workflow created successfully",
  "workflowId": "665e4a34c65bb95f2f2d72e1"
}
```

### Request body fields

All fields besides `title` are optional. Each module object attaches (and enables) that step in the workflow. Modules run in this order during execution: `agent` (call) → `email` → `sms` → `calendar`.

| Field                                             | Type                                                      | Description                                                                                                    |
| ------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `title`                                           | `string`                                                  | Workflow name. Required.                                                                                       |
| `callbackUrl`                                     | `string`                                                  | HTTPS URL that receives async workflow events for this API key. Overrides the key's default callback URL.      |
| `crm.provider`                                    | `MailChimp` \| `GetResponse` \| `HubSpot` \| `Salesforce` | CRM contact list source for this workflow.                                                                     |
| `crm.listId`                                      | `string`                                                  | Contact list id from the configured CRM provider.                                                              |
| `agent.phonePurchaseId`                           | `string`                                                  | Purchased phone number id used to place the outbound call.                                                     |
| `agent.assistantId`                               | `string`                                                  | Assistant id to run the call.                                                                                  |
| `email.provider`                                  | `GoogleEmail` \| `MicrosoftEmail` \| `ZohoEmail`          | Email integration to send from. Must already be connected via `/integrations/oauth/{provider}/email/initiate`. |
| `email.subject` / `email.content`                 | `string`                                                  | Supports `{{name}}`, `{{email}}`, `{{phone}}`, `{{callTranscript}}`, `{{callSummary}}` placeholders.           |
| `email.save_history`                              | `boolean`                                                 | Persist sent emails to workflow history.                                                                       |
| `email.send_summary`                              | `boolean`                                                 | Include the call transcript/summary placeholders (requires `agent` to be set).                                 |
| `sms.provider`                                    | `Twilio` \| `ClickSend`                                   | SMS integration to send from.                                                                                  |
| `sms.phone_number`                                | `string`                                                  | Sender phone number registered with the provider.                                                              |
| `sms.subject` / `sms.content`                     | `string`                                                  | Message content; supports the same placeholders as `email.content`.                                            |
| `calendar.provider`                               | `GoogleCalendar` \| `MicrosoftCalendar` \| `ZohoCalendar` | Calendar integration used to create a follow-up event after a call.                                            |
| `webhook.url`                                     | `string`                                                  | HTTPS endpoint that receives the call result payload (transcript, analysis, status).                           |
| `report.forward_to_email` / `report.email`        | `boolean` / `string`                                      | Email a run report to the given address.                                                                       |
| `report.forward_to_webhook` / `report.webhookUrl` | `boolean` / `string`                                      | Forward a run report to the given webhook.                                                                     |
| `endCall.phrases`                                 | `string[]`                                                | Phrases that make the assistant end the call early (e.g. `"goodbye"`).                                         |

<Note>
  Email and calendar modules require an active integration of the matching
  provider and type (`EMAIL` / `CALENDAR`) connected for your organization via
  `POST /integrations/oauth/{provider}/email/initiate` or
  `.../calendar/initiate`. If the integration's OAuth token can't be refreshed
  (e.g. the connection was revoked), the module is skipped and the failure
  reason is recorded on the workflow run instead of stopping the whole workflow.
</Note>

### Common status codes

* `201` created
* `400` validation error
* `403` missing `workflows:write`
* `500` server error

## `POST /v1/workflows/{id}/run`

Triggers immediate workflow execution.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID/run" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}/run`,
    {
      method: 'POST',
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  response = requests.post(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}/run",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `201 Created`

```json theme={null}
{
  "status": true,
  "message": "Workflow execution started",
  "jobId": "job_01hxyz"
}
```

### Common status codes

* `201` execution started
* `403` missing `workflows:write`
* `404` workflow not found
* `500` server error

## `GET /v1/workflows/jobs/{jobId}`

Returns scheduler job status.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/workflows/jobs/job_01hxyz" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const jobId = 'job_01hxyz';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/jobs/${jobId}`,
    {
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  job_id = "job_01hxyz"
  response = requests.get(
      f"https://api.indigenius.ai/v1/workflows/jobs/{job_id}",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### Common status codes

* `200` success
* `403` missing `workflows:read`
* `404` job not found
* `500` server error

## `POST /v1/workflows/schedule`

Schedules workflow execution. Body is DTO-accurate to `ScheduleWorkflowDto`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.indigenius.ai/v1/workflows/schedule" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "workFlowId": "665e4a34c65bb95f2f2d72e1",
      "scheduledDate": "2026-07-01T09:00:00.000Z",
      "timezone": "GMT_plus_1"
    }'
  ```

  ```javascript Node theme={null}
  const response = await fetch(
    'https://api.indigenius.ai/v1/workflows/schedule',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.INDIGENIUS_API_KEY,
      },
      body: JSON.stringify({
        workFlowId: '665e4a34c65bb95f2f2d72e1',
        scheduledDate: '2026-07-01T09:00:00.000Z',
        timezone: 'GMT_plus_1',
      }),
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  payload = {
      "workFlowId": "665e4a34c65bb95f2f2d72e1",
      "scheduledDate": "2026-07-01T09:00:00.000Z",
      "timezone": "GMT_plus_1",
  }
  response = requests.post(
      "https://api.indigenius.ai/v1/workflows/schedule",
      headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json=payload,
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### Common status codes

* `201` scheduled
* `400` validation error
* `403` missing `workflows:write`
* `500` server error

## `GET /v1/workflows`

Returns paginated workflows for the organization. Requires `workflows:read`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/workflows?page=1&pageSize=10" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const response = await fetch(
    'https://api.indigenius.ai/v1/workflows?page=1&pageSize=10',
    {
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  response = requests.get(
      "https://api.indigenius.ai/v1/workflows",
      headers={"X-API-Key": "YOUR_API_KEY"},
      params={"page": 1, "pageSize": 10},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflows fetched successfully",
  "data": [
    {
      "id": "665e4a34c65bb95f2f2d72e1",
      "title": "Lead followup workflow",
      "status": 1,
      "enabled": true
    }
  ],
  "meta": { "page": 1, "pageSize": 10, "totalPages": 1, "totalCount": 1 }
}
```

### Common status codes

* `200` success
* `403` missing `workflows:read`
* `500` server error

## `GET /v1/workflows/{id}`

Returns workflow details, including the attached module configuration (CRM, agent, email, SMS, webhook, report, calendar, end call). Requires `workflows:read`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}`,
    {
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  response = requests.get(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflow fetched successfully",
  "data": {
    "id": "665e4a34c65bb95f2f2d72e1",
    "title": "Lead followup workflow",
    "structure": {},
    "enabled": true
  }
}
```

### Common status codes

* `200` success
* `403` missing `workflows:read`
* `404` workflow not found
* `500` server error

## `PATCH /v1/workflows/{id}`

Updates workflow metadata, structure, and enabled state. Body is DTO-accurate to `UpdateWorkFlowDto`; all fields are required and fully replace the existing values. Requires `workflows:write`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X PATCH "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Lead follow-up (updated)",
      "structure": {},
      "enabled": true
    }'
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}`,
    {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.INDIGENIUS_API_KEY,
      },
      body: JSON.stringify({
        title: 'Lead follow-up (updated)',
        structure: {},
        enabled: true,
      }),
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  payload = {
      "title": "Lead follow-up (updated)",
      "structure": {},
      "enabled": True,
  }
  response = requests.patch(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}",
      headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
      json=payload,
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflow updated successfully"
}
```

### Common status codes

* `200` updated
* `400` validation error
* `403` missing `workflows:write`
* `404` workflow not found
* `500` server error

## `DELETE /v1/workflows/{id}`

Deletes a workflow and its associated modules (CRM, agent, email, SMS, webhook, report, calendar, end call). This is irreversible. Requires `workflows:write`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X DELETE "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}`,
    {
      method: 'DELETE',
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  response = requests.delete(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflow deleted successfully"
}
```

### Common status codes

* `200` deleted
* `403` missing `workflows:write`
* `404` workflow not found
* `500` server error

## `POST /v1/workflows/{id}/cancel`

Cancels a queued, waiting, or active workflow run by removing its pending jobs from the queue. Requires `workflows:write`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID/cancel" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}/cancel`,
    {
      method: 'POST',
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  response = requests.post(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}/cancel",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflow canceled successfully"
}
```

### Common status codes

* `200` canceled
* `403` missing `workflows:write`
* `404` workflow not found
* `500` server error

## `GET /v1/workflows/{id}/jobs`

Returns all scheduler jobs (completed, active, waiting, failed, paused, delayed) linked to a workflow, with an aggregate count per state. Requires `workflows:read`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID/jobs" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}/jobs`,
    {
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  response = requests.get(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}/jobs",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflow jobs fetched successfully",
  "data": [
    { "id": "job_01hxyz", "status": "completed" },
    { "id": "job_01hyza", "status": "active" }
  ]
}
```

### Common status codes

* `200` success
* `403` missing `workflows:read`
* `500` server error

## `GET /v1/workflows/{id}/summary`

Returns a high-level execution summary (total contacts processed, completed, failed) for the workflow. Requires `workflows:read`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID/summary" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}/summary`,
    {
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  response = requests.get(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}/summary",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflow summary fetched successfully",
  "data": {
    "totalContacts": 120,
    "completed": 98,
    "failed": 22
  }
}
```

### Common status codes

* `200` success
* `403` missing `workflows:read`
* `404` workflow not found
* `500` server error

## `GET /v1/workflows/{id}/summary/report`

Returns a detailed per-contact report for every run of the workflow, including call, email, SMS, and calendar module outcomes. Requires `workflows:read`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID/summary/report" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}/summary/report`,
    {
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  response = requests.get(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}/summary/report",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflow report fetched successfully",
  "data": {
    "id": "665e4a34c65bb95f2f2d72e1",
    "report": [{ "contact": "+14155552671", "status": "completed" }]
  }
}
```

### Common status codes

* `200` success
* `403` missing `workflows:read`
* `404` workflow not found
* `500` server error

## `GET /v1/workflows/{id}/summary/timeline`

Returns a chronological list of execution events (started, module executed, contact completed, etc.) for the workflow. Requires `workflows:read`.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X GET "https://api.indigenius.ai/v1/workflows/WORKFLOW_ID/summary/timeline" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node theme={null}
  const workflowId = 'WORKFLOW_ID';
  const response = await fetch(
    `https://api.indigenius.ai/v1/workflows/${workflowId}/summary/timeline`,
    {
      headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
    },
  );
  console.log(await response.json());
  ```

  ```python Python theme={null}
  import requests
  workflow_id = "WORKFLOW_ID"
  response = requests.get(
      f"https://api.indigenius.ai/v1/workflows/{workflow_id}/summary/timeline",
      headers={"X-API-Key": "YOUR_API_KEY"},
      timeout=30,
  )
  print(response.status_code)
  print(response.json())
  ```
</CodeGroup>

### `200 OK`

```json theme={null}
{
  "status": true,
  "message": "Workflow timeline fetched successfully",
  "data": [
    { "at": "2026-06-02T10:00:00.000Z", "event": "workflow.started" },
    { "at": "2026-06-02T10:01:22.000Z", "event": "workflow.completed" }
  ]
}
```

### Common status codes

* `200` success
* `403` missing `workflows:read`
* `404` workflow not found
* `500` server error

## Recommended flow

1. Create workflow.
2. Run once to validate behavior.
3. Schedule if needed.
4. Monitor jobs and summary endpoints.