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

# Start node

# Start Event Node

The entry point for every workflow - configure triggers, execution mode, and initial data.

The **Start Event Node** is the required entry point for every workflow. It defines how the workflow is triggered, how it executes, and what initial data it receives.

> [!NOTE]
>
> Every workflow must have exactly one Start Event Node. It's automatically added when you create a new workflow.

## Overview

The Start Event Node controls:

| Setting | Purpose |
| - | - |
| **Trigger Method** | How the workflow is invoked (API call, Voice AI tool, etc.) |
| **Execution Mode** | Synchronous or asynchronous processing |
| **Default Context** | Initial data structure and default values |
| **Environment Config** | QA and Production trigger endpoints |

***

## Configuration

Click on the Start Event Node to open its configuration panel.

### Execution Mode

Toggle **Start asynchronously** to control how your workflow responds when triggered:

> [tab] Asynchronous (Recommended)
>
> **Toggle: ON**
>
> * Workflow returns an immediate response when triggered
> * Processing continues in the background
> * Caller doesn't wait for workflow completion
>
> **Best for:**
>
> * FNOL intake and claims processing
> * Policy updates and servicing requests
> * Any workflow with external API calls
> * Long-running processes
>
> ```json theme={null}
> // Immediate response
> {
>   "status": "accepted",
>   "instanceId": "exec-12345-6789"
> }
> ```

> [tab] Synchronous
>
> **Toggle: OFF**
>
> * HTTP request waits until the entire workflow completes
> * Returns the final workflow response after all nodes execute
> * Caller is blocked until completion
>
> **Best for:**
>
> * Quick lookups that need immediate results
> * Real-time policy verification
> * Simple data transformations
>
> ```json theme={null}
> // Response after workflow completes
> {
>   "status": "completed",
>   "result": {
>     "policyNumber": "HO-12345678",
>     "coverageStatus": "active"
>   }
> }
> ```

> [!WARNING]
>
> Synchronous workflows can timeout if processing takes too long. Use async for any workflow that calls external APIs or performs complex operations.

***

### Default Context

The **context** is your workflow's data storage—a JSON object that travels through every node. Configure default values in the Start Event Node.

Click **+ Set Default workflow content** to define the initial structure:

```json theme={null}
{
  "claimType": null,
  "policyNumber": null,
  "claimant": {
    "firstName": null,
    "lastName": null
  }
}
```

#### System Properties

Every workflow execution automatically includes these system properties:

| Property | Description | Example |
| - | - | - |
| `tenantId` | Your organization identifier (from platform URL) | `acme-insurance` |
| `environment` | Current execution environment | `_preview`, `qa`, `prod` |
| `instanceId` | Unique ID for this specific execution | `exec-12345-6789` |
| `correlationId` | Links related workflow executions together | `d7a6bdf5-fec4-4876-...` |

**Example context at workflow start:**

```json theme={null}
{
  "tenantId": "acme-insurance",
  "environment": "prod",
  "instanceId": "exec-12345-6789",
  "correlationId": "d7a6bdf5-fec4-4876-a4c9-e8b2c1a3dc2",
  "claimType": null,
  "policyNumber": null,
  "claimant": {
    "firstName": null,
    "lastName": null
  }
}
```

> [!TIP]
>
> Use `correlationId` to trace related workflows. When one workflow triggers another, they share the same correlation ID—useful for debugging complex processes.

***

### Manual Triggering

The Start Event Node displays **cURL commands** for manually triggering the workflow via HTTP. This is useful for testing outside of Preview mode.

**QA Environment:**

```bash theme={null}
curl -X POST https://api.liberateinc.com/v1/workflows/{slug}/execute \
  -H "Authorization: Bearer YOUR_QA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policyNumber": "HO-12345678",
    "claimant": {
      "firstName": "John",
      "lastName": "Smith"
    }
  }'
```

**Production Environment:**

```bash theme={null}
curl -X POST https://api.liberateinc.com/v1/workflows/{slug}/execute \
  -H "Authorization: Bearer YOUR_PROD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policyNumber": "HO-12345678",
    "claimant": {
      "firstName": "John",
      "lastName": "Smith"
    }
  }'
```

The `{slug}` is the unique workflow identifier visible in your browser URL when editing the workflow.

***

### Styling

Customize the node's visual appearance on the canvas:

| Option | Description |
| - | - |
| **Color** | Change the node's background color for visual organization |
| **Icon** | Select an icon to represent the workflow's purpose |

Styling is optional and doesn't affect workflow execution—it's purely for visual organization when building complex workflows.

***

## How Data Enters the Workflow

Data can enter through the Start Event Node in several ways:

### From Voice AI

When Voice AI triggers a workflow (via a Tool), it passes the conversation transcript and any extracted data:

```json theme={null}
{
  "tenantId": "acme-insurance",
  "environment": "prod",
  "instanceId": "exec-12345-6789",
  "correlationId": "abc-123-def",
  "transcript": "Assistant: How can I help? User: I need to file a claim...",
  "callerPhone": "+1-555-123-4567",
  "callId": "call-98765"
}
```

### From API Request

When triggered via HTTP API, the request body becomes part of the context:

```bash theme={null}
curl -X POST .../workflows/{slug}/execute \
  -d '{"policyNumber": "HO-12345678", "action": "lookup"}'
```

Results in context:

```json theme={null}
{
  "tenantId": "acme-insurance",
  "environment": "prod",
  "instanceId": "exec-12345-6789",
  "correlationId": "abc-123-def",
  "policyNumber": "HO-12345678",
  "action": "lookup"
}
```

### From Another Workflow

When one workflow calls another, it can pass data through the invocation:

```json theme={null}
{
  "tenantId": "acme-insurance",
  "environment": "prod",
  "instanceId": "exec-new-instance",
  "correlationId": "abc-123-def",  // Same as parent workflow
  "parentWorkflowId": "exec-12345-6789",
  "claimData": { ... }
}
```

***

## Best Practices

### Define Clear Default Context

Set up a default context structure that matches what your workflow expects:

```json theme={null}
{
  "claim": {
    "type": null,
    "description": null,
    "lossDate": null
  },
  "policy": {
    "number": null,
    "holder": null
  },
  "processed": false,
  "errors": []
}
```

This makes it clear what data the workflow needs and provides a consistent structure for downstream nodes.

### Use Async for External Calls

If your workflow calls any external API (Snapsheet, Guidewire, your AMS), use asynchronous execution to avoid timeouts.

### Document with Styling

Use colors to categorize workflows visually:

| Color | Suggested Use |
| - | - |
| 🟢 Green | Claims workflows |
| 🔵 Blue | Policy servicing |
| 🟡 Yellow | Billing and payments |
| 🟣 Purple | Integrations and sync |

***

## Common Issues

### Workflow Times Out

**Symptom:** Synchronous workflow returns a timeout error.

**Fix:** Switch to asynchronous execution, or optimize the workflow to complete faster.

### Missing Context Data

**Symptom:** Downstream nodes can't find expected data.

**Fix:** Verify that the triggering system (Voice AI, API) is sending the expected payload. Check the default context structure.

### Wrong Environment

**Symptom:** Workflow connects to QA systems when it should use Production.

**Fix:** Check the `environment` property in context. Ensure you're triggering the correct environment endpoint.

***

## Next Steps

> [card] [Context Deep Dive](https://docs.liberate.ai/workflows/concepts/context.md)
>
> Learn how data flows through workflows

> [card] [Mapping Node](https://docs.liberate.ai/workflows/nodes/mapping-node.md)
>
> Transform data after it enters the workflow

> [card] [Task Node](https://docs.liberate.ai/workflows/nodes/task-node.md)
>
> Call external systems from your workflow

> [card] [End Event Node](https://docs.liberate.ai/workflows/nodes/end-node.md)
>
> Complete the workflow and return responses


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