Workflows

• When an order is reserved, put it in the calendar, open the preparation task and tell the warehouse.
• When an invoice is validated, wait for its due date, remind the customer if it is still unpaid, and escalate a week later.
• Every weekday at 07:00, ask Neo what leaves and what comes back today, and post it where the team reads.
• When a payment is recorded, add it to the invoice in your accounting package, and leave a task if it cannot be posted.
• When an email arrives, file the invoices, route the requests and leave a summary in the chat.

Each of these is a ready-made template. To see how the pieces fit, read How workflows work; to build one now, start with the quickstart.

Every workflow has one trigger. These are the seven types; the list in the API reports six of them in the type of the trigger (a workflow started only by another workflow, like one that was never published, comes back with no type). See Triggers for each one.

The API and MCP are meant to start workflows with a manual trigger.

The list returns each workflow with how it starts and, for a manual one, the run form: the fields that the run requires in payload, read from the published version. It never returns the definition of the workflow. Only administrators can read it, and the workflows come sorted by name.

Starting a run queues the published version of the workflow, as the Run button does for a manual trigger (the button also publishes a draft that has changes first; the API never does). The call returns the identifier of the run and the status it is born with, queued. It does not wait for the run to finish, and the API has no operation or tool that reads a run: its progress is only visible in the Filmo app. If the workflow declares a run form, its fields are required in payload, and a request that misses one answers 400 and starts nothing. A workflow that has never been saved answers 409.

Starting a run should carry an Idempotency-Key of your own: two requests with the same key return the same run instead of starting two. Without one, two requests are two runs. See the guide on idempotency in the REST API tab.

The details, with the scopes, the errors and the way to learn the outcome, are in Workflows from the API and MCP.

• A write made through the API or MCP goes through the same path as the same change in the app. A workflow whose trigger is an event starts for real when that change happens, not only when someone works in the app. The event reaches the workflow with its origin set to API or MCP.
• That holds when the action behind the endpoint is one of the events of the catalog. Which endpoints map to one is not listed here endpoint by endpoint.
• The event is sent after the response, once per change, and it is not retried if it fails. A repeated Idempotency-Key returns the stored response and does not send the event again.
• You cannot ask a request not to set off workflows. What you can do is check which workflows are active before you load or import data, and, in a workflow, filter an event trigger on where the change came from.
• Some changes have no event, such as most updates to items and prices, notes, tags and the planner.
• A write made by a workflow can start other workflows. Filmo stops a chain of workflows at a depth limit of ten and does not start a workflow that is already in the chain. A workflow that calls the API with a key is expected to start a new chain, because the call reaches Filmo as a request of the API; so keep that call away from the data that starts the workflow, or the two can loop.

To keep another system in step with Filmo, the guide Syncing data explains how to build push with a workflow whose trigger is an event and whose step is an HTTP request to your endpoint; the guide Push changes to your own system builds it.