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

# Using Flows

<Info>Flows is currently in beta and is subject to change as the platform evolves</Info>

Flows gives you a standard way to run multi-step Sohar workflows through the API.

From an integration perspective, the model is simple: you choose a Flow template, start a Run, monitor its status, and read the final output when it completes. If the workflow needs additional information partway through, the Run can pause and wait for input before continuing.

## Flows & Runs

A **Flow** template is the reusable definition of a workflow. It describes the states the workflow will execute, the input it expects, and the output it produces.

A **Run** is a single execution of that template. Each Run represents one real workflow instance, such as processing a specific patient or payer request.

## Starting a Run

To use a Flow, your application starts a Run from a template. This can either be started in the Sohar dashboard or using the [Create Run](/api-reference/runs/create-run) API.

When a Run is created, you provide the input data required by that template. The API returns a `flowRunId`, which becomes the ID your application uses to track and interact with that workflow execution.

Flows are asynchronous and may not complete immediately. This makes them better suited for orchestration, automation, and multi-step processing than a single request-response API call.

## Input

Each Flow template defines the input it expects when a Run starts. When creating a Run, your application provides that data as `inputData`.

Because Flows are template-driven, the required input can vary between templates. Some Flows have everything they need up front, while others may request additional input later through a callback step. In that case, the initial `inputData` starts the workflow, and a later callback input resumes it.

## Tracking Progress

A Run moves through a small set of statuses:

* `CREATED`: the Run has been accepted
* `IN_PROGRESS`: the workflow is actively executing
* `PENDING`: the workflow is paused and waiting for additional input
* `COMPLETE`: the workflow finished successfully and output is available
* `ERROR`: the workflow ended with an error

For most integrations, there are two common patterns:

* Poll the [Get Run](/api-reference/runs/get-run) API until the status reaches `COMPLETE`, `PENDING`, or `ERROR`
* Listen for webhook events and react when the Run changes state

Polling is usually the simplest way to get started. Webhooks are a better fit when you want your system to react to workflow progress asynchronously without repeated status checks.

## Handling Paused Runs

Some Flows include callback states. These are pause points where the workflow needs more information before it can continue.

When that happens, the Run moves to `PENDING`. At that point, you can submit the required input and resume the workflow using the [Update Run](/api-reference/runs/update-run) API. Once the new input is accepted, the Flow continues execution and transitions back to `IN_PROGRESS`.

This is useful for human-in-the-loop workflows, conditional data collection, or integrations where not all required information is available at the start of the process.

## Output

The shape of that output is defined in the template. During execution, data is gathered and processed across states, and when the Run reaches `COMPLETE` it returns the template-defined output for that specific workflow instance.

## Versions

Flows are versioned through their templates.

You can run the latest version of a template or explicitly target a specific version. In practice, this gives teams flexibility during development and change management:

* Use the latest version when you want to adopt the current workflow definition automatically
* Pin to a specific version when you need stable, repeatable behavior in production