Start a workflow

Use this when something on your own website should start your follow-up in Lahuta: a quote request, a price calculator, a "call me back" form. You build the workflow in the dashboard. Your site sends the person, and they go through its steps the same as someone you start from the dashboard.

Before you startCopy Anchor Link

The workflow must:

• Have the Manually or via API trigger. Workflows started by a booking, a group, an event or a message can't be started through the API.
• Be Active. A draft, paused or archived workflow starts nobody.

To get the workflow's ID, open it from Marketing → Workflows, open the ⋯ menu in the editor and select Copy workflow ID. The ID stays the same when you publish changes. A duplicate gets an ID of its own.

See Workflows for building one.

Start someoneCopy Anchor Link

POST /v1/workflows/{workflowId}/start starts one contact. Send the person's details as contact, the same way as PUT /v1/contacts. The contact is saved or matched first, then started.

Here Northside Pottery's commission quote calculator starts everyone who asks for a quote in its "Commission follow-up" workflow:

curl -X POST https://api.lahuta.org/v1/workflows/0197b3a1-6c0e-7d42-9a1f-3e8b5c2d7f14/start \
  -H "X-Api-Key: $LAHUTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "kind": "person",
      "firstName": "Rafael",
      "lastName": "Okoye",
      "emails": [{ "label": null, "value": "rafael.okoye@example.com" }],
      "phones": [{ "label": null, "value": "+15035550167" }],
      "source": "quote-calculator"
    }
  }'

{
  "contactId": "0197b3a2-1f5d-7e08-8b3c-4a9d6e2f1c73",
  "result": "started"
}

Who to startCopy Anchor Link

contact takes one of two shapes:

• The person's details, with the same fields as PUT /v1/contacts, except note. They're matched to a contact you already have by email (or by phone when there's no email), or saved as a new contact. A source is only saved when the contact doesn't have one yet.
• A contact you already have, by kind and id, like { "kind": "person", "id": "0197b2e4-6a1c-7f02-8d3e-5b9a1c4f2e61" }. Use "company" for a company. You get the id from PUT /v1/contacts, or by looking the contact up.

Calling twiceCopy Anchor Link

result is started, or already_running when the contact is going through this workflow right now. Nothing new starts, so a retry or a form submitted twice is safe, and the call needs no idempotency key. Once their run ends, another call starts them again.

What happens nextCopy Anchor Link

• The person starts at the first step of the workflow's published version, the same as when you select Start for contacts in the dashboard.
• Their run shows under View runs in the workflow's ⋯ menu.
• The steps can use the contact's personal values, like {{lahuta:first_name}} or {{lahuta:source}}. The call adds no values of its own.
• A text step only sends if the person's number agreed to your marketing texts. When your form asks, record their consent before you start the workflow.

If the steps need the form's answers, like the size of a commission, write them to a group with PUT /v1/groups instead, and start the workflow with the Added to a group trigger. Its steps can use the group's columns.

ErrorsCopy Anchor Link

When a call is refused, nothing is saved and nobody starts.

See Workflows in the API reference for every field.

RelatedCopy Anchor Link