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

# Workflows

> Workflows automate multi-step call and text outreach with reusable definitions, schedules, and per-contact executions.

Workflows let you orchestrate outreach over time instead of sending a single call or message. They are useful for sequences like qualification, collections, reminders, re-engagement, and follow-up.

## Workflow Model

* A **workflow** is the reusable template.
* An **execution** is one run of that workflow for one contact.

This means you can define a sequence once and run it for many contacts with different variables and metadata.

## What a Workflow Can Do

* Mix call and text steps
* Delay between steps
* Stop early based on outcomes
* Respect schedule windows
* Launch one execution or many in bulk

## Scheduling

Feather supports two layers of timing:

* **Workflow schedule**: when the workflow itself is allowed to run in its configured timezone
* **TCPA schedule**: when contact attempts are allowed in the recipient's local timezone

Use workflow schedule for business operations. Use TCPA schedule for compliance controls.

## Example Workflow Definition

This example calls first, then sends a text follow-up if the workflow is still active.

```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/workflow" \
  -H "X-API-Key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Two-step follow-up",
    "description": "One call and one text reminder",
    "active": true,
    "timezone": "America/New_York",
    "workflowSchedule": {
      "monday": {
        "enabled": true,
        "timeRanges": [
          { "startHour": 9, "startMinute": 0, "endHour": 17, "endMinute": 0 }
        ]
      },
      "tuesday": {
        "enabled": true,
        "timeRanges": [
          { "startHour": 9, "startMinute": 0, "endHour": 17, "endMinute": 0 }
        ]
      }
    },
    "definition": {
      "steps": [
        {
          "type": "CALL",
          "order": 1,
          "delayInSecs": 0,
          "agentId": "CALL_AGENT_ID",
          "leaveVoicemail": true,
          "finishOn": ["CALENDLY", "NOT_INTERESTED", "DNC"]
        },
        {
          "type": "TEXT",
          "order": 2,
          "delayInSecs": 86400,
          "agentId": "TEXT_AGENT_ID",
          "initialMessage": "Hi {{firstName}}, following up on our earlier outreach. Let me know if you want to reconnect.",
          "finishOn": ["DNC"]
        }
      ]
    }
  }'
```

## Starting an Execution

Executions carry the contact record for one run.

```bash theme={"system"}
curl -X POST "https://prod.featherhq.com/api/v1/workflow/WORKFLOW_ID/execution" \
  -H "X-API-Key: $FEATHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerLeadId": "contact-123",
    "primaryPhone": "+14155550123",
    "zipcode": "94107",
    "variables": {
      "firstName": "Taylor"
    },
    "metadata": {
      "firstName": "Taylor",
      "campaign": "renewal-q2"
    },
    "priorityDate": "2026-03-12T10:00:00Z"
  }'
```

## Common Controls

You can manage executions after creation:

* List active or historical runs
* Pause and resume
* Cancel a single execution
* Cancel by lead ID
* Cancel by phone number
* Bulk create up to a batch of contacts

## Best Practices

* Keep each workflow focused on one business goal.
* Use variables for contact-specific content instead of duplicating workflows.
* Separate channel logic by step type instead of overloading one prompt.
* Use finish conditions aggressively to avoid unnecessary follow-up.
* Test new versions before attaching them to large workflows.

## Related Guides

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/documentation/core-concepts/agents">
    Choose the right agent for each step.
  </Card>

  <Card title="Phone Numbers" icon="phone" href="/documentation/core-concepts/phone-numbers">
    Configure the numbers workflows call from.
  </Card>

  <Card title="Workflows API" icon="code" href="/api-reference/workflows/create-agent-workflow">
    Browse workflow creation and execution endpoints.
  </Card>

  <Card title="Testing Lab" icon="flask" href="/documentation/core-concepts/testing-lab">
    Test agent behavior before attaching it to automation.
  </Card>
</CardGroup>