Vantax AIDocs
POST

Create Workflow

Creates a new Workflow in the specified sub-account.

POSThttps://api.vantaxai.com/v1/workflows

A Workflow pairs a single `trigger` with an ordered list of `steps`. When the trigger event fires, each step runs in sequence — the `next` field on a step points to the id of the step that runs after it (use `null` to end the chain). Set `is_active` to `false` to create the Workflow in a draft state without arming the trigger.

Headers

  • Authorizationstringrequired

    Bearer authentication with your secret API key.

    example: Bearer vx_live_3fa9c2…

  • Content-Typestringrequired

    Must be application/json for requests with a body.

    example: application/json

Body Parameters

  • namestringrequired

    Display name of the Workflow.

    example: New Lead Follow-up

  • sub_account_idstringrequired

    Sub-account that will own the Workflow.

    example: sub_8a1f4c2e

  • triggerobjectrequired

    The event that starts the Workflow. An object with a `type` (see Workflow Triggers) and a `config` of trigger-specific filters.

  • trigger.typestringrequired

    The trigger event type.

    contact.createdappointment.createdmessage.receivedcall.completedcustom.event

    example: contact.created

  • trigger.configobjectrequired

    Filters scoping when the trigger fires (e.g. `{ "source": "website" }`).

  • stepsarrayrequired

    Ordered list of step objects. Each step has an `id`, a `type`, a `config`, and a `next` (the id of the following step, or `null`).

  • steps[].idstringrequired

    Unique id for the step within the Workflow.

    example: step_send_sms

  • steps[].typestringrequired

    The action the step performs.

    send_smssend_emailadd_tagremove_tagcreate_appointmentstart_callwaithttp_request

    example: send_sms

  • steps[].configobjectrequired

    Action-specific configuration for the step.

  • steps[].nextstringoptional

    Id of the next step to run, or `null` to end the Workflow.

  • descriptionstringoptional

    Internal description of what the Workflow does.

  • is_activebooleanoptional

    Whether the trigger is armed. Defaults to true.

Request

curl -X POST https://api.vantaxai.com/v1/workflows \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Lead Follow-up",
    "sub_account_id": "sub_8a1f4c2e",
    "trigger": {
      "type": "contact.created",
      "config": { "source": "website" }
    },
    "steps": [
      {
        "id": "step_send_sms",
        "type": "send_sms",
        "config": { "agent_id": "agt_3d9b21", "template": "Welcome! Reply to book a call." },
        "next": "step_add_tag"
      },
      {
        "id": "step_add_tag",
        "type": "add_tag",
        "config": { "tag_id": "tag_9f02" },
        "next": null
      }
    ]
  }'

Response

{
  "success": true,
  "message": "Workflow created successfully",
  "data": {
    "id": "wf_4c81a0",
    "name": "New Lead Follow-up",
    "description": null,
    "trigger": {
      "type": "contact.created",
      "config": { "source": "website" }
    },
    "steps": [
      {
        "id": "step_send_sms",
        "type": "send_sms",
        "config": { "agent_id": "agt_3d9b21", "template": "Welcome! Reply to book a call." },
        "next": "step_add_tag"
      },
      {
        "id": "step_add_tag",
        "type": "add_tag",
        "config": { "tag_id": "tag_9f02" },
        "next": null
      }
    ],
    "is_active": true,
    "sub_account_id": "sub_8a1f4c2e",
    "created_at": "2026-01-14T10:30:00Z"
  }
}