# Build a workflow

> Start from one of three templates or build on the canvas from scratch, then wire up steps for research, branching, loops, and CRM writes until the checklist says everything is configured.

- Source: https://spiich.ai/help/workflows/build-a-workflow
- Section: Workflows
- Who can do this: Everyone
- Time: 15 minutes
- Last updated: 2026-08-24

## Before you start

- A workflow already created. See [What workflows are](/help/workflows/workflows-overview).
- A connected CRM, so there are record types and fields for steps to work with.
- An active subscription or trial.

Every workflow is built the same way once it exists: steps on a canvas, wired together, each one configured in a panel on the right. Where you start from, a template or a blank canvas, only changes how much is already filled in.

## Two ways to start

1. **Start from a template**
   Open a workflow with no steps yet and pick one of three cards: **Daily record research** (every morning, research matching records and write the results back, on an 08:00 schedule), **Qualify and route records** (judge matching records against your criteria and route by decision), or **Enrich records on demand** (run by hand over matching records and fill in missing fields). Each template resolves to your workspace's own record types and fields; anything it cannot resolve is left blank and flagged on the checklist. Template write-backs default to filling only empty fields, so nothing curated gets overwritten.

2. **Or start from scratch**
   Click **Start from scratch** on the same setup screen and build the canvas step by step yourself, picking each step type from the library as you go.

## The canvas

A workflow is drawn top to bottom: a **Trigger** node at the top, then step cards connected by arrows, with branch labels on the edges where a Branch step splits the path. Click the plus on a card, on a connector, or **Inside** a loop card to add a step there. Click a card to open its settings in the right-hand panel, where you can rename it and, with the bin icon, delete it. Steps that use an agent carry a **Metered** chip, because they run on credits.

## The step library

Every step you can add is grouped into five categories.

| Category | Step | What it does |
| --- | --- | --- |
| AI | Run an agent | Let an agent research and return validated, structured output. |
| Logic | Branch | Send each record down a different path depending on what was decided. |
| Logic | For each | Run a set of steps once per record or value in a list. |
| Logic | Keep looking | Repeat steps until it has found as many as you asked for. |
| Data checks | Skip ones you have | Separate genuinely new records from ones already in your CRM. |
| CRM writes | Save to CRM | Create, update, or link records. The only step that writes. |
| CRM writes | Save note | Attach a note to a record. |
| Outcome | Set outcome | Record how this item turned out, so the run can report on it. |

## Configuring an agent step

Click a **Run an agent** step to open its panel. The agent itself is fixed, shown as the **Workflow agent**, general-purpose with the tools available to this workflow; you cannot swap it for a different one. Write free-text **Instructions** describing what it should do, for example "Find companies that match our ideal customer profile." Then choose what it **must return**: a single record, a list of CRM records, a decision, a decision per item, one custom object, or a list of custom objects. Under **Returned fields**, define the fields the agent has to fill (Text, Number, Yes/no, One of a set, or URL), and mark any of them **Required** or **Evidence required**. Give the result a name under **Save result as**, for example `companyDrafts`, so later steps can read it. The panel states plainly that this step runs on usage-based credits.

## Configuring a CRM write step

A **Save to CRM** step has four actions: **Find or create one record**, **Find or create many records**, **Update a record**, or **Link records**. For either find-or-create action you set **Identity rules**: which CRM fields recognize an existing record before a new one is created, each with a match strategy (Exact match, Normalized domain, Normalized URL, Normalized phone, or Fuzzy as a fallback only). You also decide what happens **if multiple records match** (fail this item, fail the whole run, or mark needs review) and **if no record matches** (create a new one, skip the item, or fail this item).

Under **Set fields**, map CRM fields to values from earlier steps, and set each mapping to **Always write** or **Only if empty**. Only if empty is the safer default when a workflow might touch records a person has already curated; it fills a blank field but never overwrites one that already has something in it.

**Save note** is simpler: pick the record to attach it to, and give it a title and markdown content.

## Loops and outcomes

**For each** runs its inner steps once per item in a list you choose, with a **Concurrency** setting and a choice for what happens **on item failure**: continue the other items, or fail the whole run.

**Keep looking** repeats its inner steps until it hits a **Target count** or runs out of **Max attempts**, optionally removing duplicates against a CRM record type while it collects.

**Set outcome** tags how an item finished: **Enriched** (completed successfully), **Partial** (some data found, not everything), **Skip** (intentionally skipped), or **Failed** (could not be processed), plus an optional short **Reason tag** that shows up in the run's statistics.

## The checklist that blocks you

The details panel keeps a live **Checklist** of everything not yet configured, split into real blockers and warnings. A blocker refuses **Save**, **Run** and **Activate** outright; the header shows a red count and "Needs fixing." Every entry is clickable and jumps straight to the step or the trigger it is about. A brand-new workflow with no steps yet shows no red count, only "Add at least one step before saving." Common blockers: a loop with nothing inside it, a Branch step with no branch values, or a find-or-create write step with no identity rules.

## If something goes wrong

**The header shows "Needs fixing" and Save does nothing.** Click the red problem count, or open the Checklist in the details panel, and work through each entry in order; every one jumps to the exact step that needs attention.

**A workflow keeps creating duplicate CRM records.** The Save to CRM step has no identity rules, or the wrong ones, so it cannot recognize an existing record before creating a new one. Open the step and add identity rules on the fields that actually identify a record, like a domain or an email, with a suitable match strategy. Mapped fields under Set fields only write values; they do not prevent duplicates on their own.

**A workflow overwrote data you had already cleaned up.** A field mapping was set to Always write. Change it to Only if empty and save a new version; a run that already completed cannot be undone.

## Frequently asked questions

### Can I change a template's steps after creating the workflow?

Yes. A template only seeds the starting steps; once the workflow exists, every step is editable exactly like one you built from scratch.

### What's the difference between Find or create and Update?

Find or create checks your identity rules first and only makes a new record if nothing matches. Update assumes the record already exists and changes it directly, with no identity check.

### Can a step read the output of an earlier step?

Yes, through the name you gave it under Save result as. You can also open a step's advanced input mappings to reference a specific field on an earlier result rather than the whole thing.

### Why does a step I add inside a loop only run once per item?

That is what "Inside" means on a For each or Keep looking card. Anything you drop there runs once for every item the loop is working through, not once for the whole run.

## Related

- [What workflows are](https://spiich.ai/help/workflows/workflows-overview)
- [Triggers and schedules](https://spiich.ai/help/workflows/workflow-triggers-and-schedules)
- [Test and monitor workflow runs](https://spiich.ai/help/workflows/test-and-monitor-workflow-runs)
- [What an agent is allowed to do](https://spiich.ai/help/background-agents/agent-permissions)