Skip to main content
Flows is currently in beta and is subject to change as the platform evolves
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. 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 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. 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