Replace the entire workflow

Replaces the whole workflow graph in one write, including any change someone else made after you read it. To add, change or remove one step, use POST /outcomes/{outcome}/nodes, PATCH /workflow or DELETE /nodes/{nodeId}. Use this one to save a node with incomplete settings, or to change if and switch nodes.

If the campaign has no workflow yet, this creates one. It replaces nodes, edges and dispositionEntries in one write. The graph holds only your own actions. Built-in steps for the agent type, such as outcome tags, scheduling the next call and alerts, run on every call and are not part of it. Node types, links and branches are checked, and loops are refused. A node may have incomplete settings, and each gap is listed in warnings.

Omitting a field does not clear it. campaignConfig and a node’s position are kept as stored when the request leaves them out, so a read-modify-write never silently discards settings you did not send. Send "campaignConfig": null to clear it on purpose.

Omitting a node does not delete it. A request that drops a node or an outcome entry that currently exists is rejected with 400 unless you pass "allowRemovals": true.

Concurrency. Send the workflow version you read as expectedVersion. If the workflow changed since then, the save is refused with 409 and nothing is overwritten. Without it, an API key or OAuth caller is refused only when another save lands while this request runs.

Required API key scope: campaign_workflows:write.

PUT

api

agent-builder

agents

{id}

campaign

workflow

cURL

curl --request PUT \
  --url https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "nodes": {
    "tag_booked": {
      "id": "tag_booked",
      "type": "add-tag",
      "config": {
        "tags": [
          "booked_via_ai"
        ]
      }
    },
    "sms_reminder": {
      "id": "sms_reminder",
      "type": "send-sms",
      "config": {
        "message": "Thanks for booking! See you soon."
      }
    }
  },
  "edges": [
    {
      "id": "e_booked",
      "source": "tag_booked",
      "target": "sms_reminder"
    }
  ],
  "dispositionEntries": {
    "SUCCESS": "tag_booked"
  }
}'

import requests

url = "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow"

payload = {
    "nodes": {
        "tag_booked": {
            "id": "tag_booked",
            "type": "add-tag",
            "config": { "tags": ["booked_via_ai"] }
        },
        "sms_reminder": {
            "id": "sms_reminder",
            "type": "send-sms",
            "config": { "message": "Thanks for booking! See you soon." }
        }
    },
    "edges": [
        {
            "id": "e_booked",
            "source": "tag_booked",
            "target": "sms_reminder"
        }
    ],
    "dispositionEntries": { "SUCCESS": "tag_booked" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    nodes: {
      tag_booked: {id: 'tag_booked', type: 'add-tag', config: {tags: ['booked_via_ai']}},
      sms_reminder: {
        id: 'sms_reminder',
        type: 'send-sms',
        config: {message: 'Thanks for booking! See you soon.'}
      }
    },
    edges: [{id: 'e_booked', source: 'tag_booked', target: 'sms_reminder'}],
    dispositionEntries: {SUCCESS: 'tag_booked'}
  })
};

fetch('https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'nodes' => [
        'tag_booked' => [
                'id' => 'tag_booked',
                'type' => 'add-tag',
                'config' => [
                                'tags' => [
                                                                'booked_via_ai'
                                ]
                ]
        ],
        'sms_reminder' => [
                'id' => 'sms_reminder',
                'type' => 'send-sms',
                'config' => [
                                'message' => 'Thanks for booking! See you soon.'
                ]
        ]
    ],
    'edges' => [
        [
                'id' => 'e_booked',
                'source' => 'tag_booked',
                'target' => 'sms_reminder'
        ]
    ],
    'dispositionEntries' => [
        'SUCCESS' => 'tag_booked'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow"

	payload := strings.NewReader("{\n  \"nodes\": {\n    \"tag_booked\": {\n      \"id\": \"tag_booked\",\n      \"type\": \"add-tag\",\n      \"config\": {\n        \"tags\": [\n          \"booked_via_ai\"\n        ]\n      }\n    },\n    \"sms_reminder\": {\n      \"id\": \"sms_reminder\",\n      \"type\": \"send-sms\",\n      \"config\": {\n        \"message\": \"Thanks for booking! See you soon.\"\n      }\n    }\n  },\n  \"edges\": [\n    {\n      \"id\": \"e_booked\",\n      \"source\": \"tag_booked\",\n      \"target\": \"sms_reminder\"\n    }\n  ],\n  \"dispositionEntries\": {\n    \"SUCCESS\": \"tag_booked\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"nodes\": {\n    \"tag_booked\": {\n      \"id\": \"tag_booked\",\n      \"type\": \"add-tag\",\n      \"config\": {\n        \"tags\": [\n          \"booked_via_ai\"\n        ]\n      }\n    },\n    \"sms_reminder\": {\n      \"id\": \"sms_reminder\",\n      \"type\": \"send-sms\",\n      \"config\": {\n        \"message\": \"Thanks for booking! See you soon.\"\n      }\n    }\n  },\n  \"edges\": [\n    {\n      \"id\": \"e_booked\",\n      \"source\": \"tag_booked\",\n      \"target\": \"sms_reminder\"\n    }\n  ],\n  \"dispositionEntries\": {\n    \"SUCCESS\": \"tag_booked\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"nodes\": {\n    \"tag_booked\": {\n      \"id\": \"tag_booked\",\n      \"type\": \"add-tag\",\n      \"config\": {\n        \"tags\": [\n          \"booked_via_ai\"\n        ]\n      }\n    },\n    \"sms_reminder\": {\n      \"id\": \"sms_reminder\",\n      \"type\": \"send-sms\",\n      \"config\": {\n        \"message\": \"Thanks for booking! See you soon.\"\n      }\n    }\n  },\n  \"edges\": [\n    {\n      \"id\": \"e_booked\",\n      \"source\": \"tag_booked\",\n      \"target\": \"sms_reminder\"\n    }\n  ],\n  \"dispositionEntries\": {\n    \"SUCCESS\": \"tag_booked\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "workflow": {
    "locationId": "loc_abc123",
    "campaignId": "cmp_123",
    "campaignConfig": {
      "callbackMode": "ai"
    },
    "nodes": {
      "tag_booked": {
        "id": "tag_booked",
        "type": "add-tag",
        "config": {
          "tags": [
            "booked_via_ai"
          ]
        }
      },
      "sms_reminder": {
        "id": "sms_reminder",
        "type": "send-sms",
        "config": {
          "message": "Thanks for booking! See you soon."
        }
      }
    },
    "edges": [
      {
        "id": "e_booked",
        "source": "tag_booked",
        "target": "sms_reminder"
      }
    ],
    "dispositionEntries": {
      "SUCCESS": "tag_booked"
    },
    "version": 4,
    "createdAt": "2026-07-01T09:15:22.000Z",
    "updatedAt": "2026-07-14T16:04:11.000Z"
  }
}

{
  "success": false,
  "error": "VALIDATION",
  "message": "Something here doesn't look right. Please check it and try again."
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Please sign in to continue."
}

{
  "success": false,
  "error": "InsufficientScope",
  "message": "This access key does not allow this action. Please ask your account admin to change its permissions.",
  "requiredScope": "campaign_workflows:write"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "We couldn't find that. It may have been moved or deleted."
}

{
  "success": false,
  "error": "CONFLICT",
  "message": "This changed while you were working on it. Please refresh and try again."
}

{
  "success": false,
  "error": "TooManyRequests",
  "message": "That's a lot at once. Please wait a moment and try again."
}

{
  "success": false,
  "error": "Internal",
  "message": "Something went wrong on our side. Please try again in a moment.",
  "ref": "3f2b8c1e-7d4a-4f8e-9b6a-2c1d0e5f7a9b"
}

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Path Parameters

string

required

Agent id.

Minimum string length: 1

Query Parameters

locationId

string

Pair with campaignId; omit both for primary campaign.

Minimum string length: 1

campaignId

string

Pair with locationId; omit both for primary campaign.

Minimum string length: 1

Body

application/json

nodes

object

required

Workflow nodes keyed by node id.

Show child attributes

edges

object[]

required

Directed connections between workflow nodes.

Show child attributes

dispositionEntries

object

required

Maps each call outcome to the id of the node that starts its action chain. Keys are uppercase outcome constants: SUCCESS/BOOKED (booked), CONFIRMED (appointment confirmed), RESCHEDULE (rebooked), TRANSFER (live-transferred), TAG_APPLIED (tag objective met, on a GoHighLevel sub-account), CALLBACK (asked for a callback), INFO_ONLY/FOLLOWUP_REQUESTED (asked for information), HUMAN_NEEDED (asked for a person), VOICEMAIL/NO_ACTION (no outcome), KILL_SWITCH (opted out), FAILED_TRANSFER (transfer did not connect). Which outcomes an agent can emit depends on its type, and an outcome the type cannot emit is refused with 400. The value is the id of a node in nodes: the first node of your action chain for that outcome. The platform composes the canonical handler for each outcome automatically, so just attach your actions here; do not build your own trigger/detector nodes to re-detect a standard outcome.

INFO_ONLY and FOLLOWUP_REQUESTED are two spellings of the same outcome ("asked for information") and are treated as interchangeable at run time: outbound agent types emit INFO_ONLY and the inbound receptionist emits FOLLOWUP_REQUESTED, and a chain wired under either spelling fires for both.

A key no agent type can emit is accepted but never fires. The response reports it as an unknown_outcome warning and does not reject the write, because graphs saved before a rename must stay readable.

Show child attributes

campaignConfig

object

Campaign-level settings saved with the workflow. Documented fields cover supported campaign controls; additional keys (including dashboard editor display state) are preserved for forward-compatible options.

Show child attributes

expectedVersion

integer

Optimistic-concurrency guard: the write is rejected with 409 if the stored version has moved on.

Required range: x >= 0

Example:

3

allowRemovals

boolean

default:false

Confirms that nodes and outcome entries missing from this request should be deleted. Without it, a request that would destroy existing nodes or outcome lanes is rejected with 400. Set it only when you have read the current graph and mean to drop those parts.

Example:

false

Response

The saved workflow.

success

boolean

required

Example:

true

workflow

object | null

required

Show child attributes

warnings

object[]

Everything about the graph that is worth knowing and was not worth refusing. Empty on a clean graph. Read this after a write: a 200 means the graph was stored, not that every node will do something.

Show child attributes

cURL

curl --request PUT \
  --url https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "nodes": {
    "tag_booked": {
      "id": "tag_booked",
      "type": "add-tag",
      "config": {
        "tags": [
          "booked_via_ai"
        ]
      }
    },
    "sms_reminder": {
      "id": "sms_reminder",
      "type": "send-sms",
      "config": {
        "message": "Thanks for booking! See you soon."
      }
    }
  },
  "edges": [
    {
      "id": "e_booked",
      "source": "tag_booked",
      "target": "sms_reminder"
    }
  ],
  "dispositionEntries": {
    "SUCCESS": "tag_booked"
  }
}'

import requests

url = "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow"

payload = {
    "nodes": {
        "tag_booked": {
            "id": "tag_booked",
            "type": "add-tag",
            "config": { "tags": ["booked_via_ai"] }
        },
        "sms_reminder": {
            "id": "sms_reminder",
            "type": "send-sms",
            "config": { "message": "Thanks for booking! See you soon." }
        }
    },
    "edges": [
        {
            "id": "e_booked",
            "source": "tag_booked",
            "target": "sms_reminder"
        }
    ],
    "dispositionEntries": { "SUCCESS": "tag_booked" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    nodes: {
      tag_booked: {id: 'tag_booked', type: 'add-tag', config: {tags: ['booked_via_ai']}},
      sms_reminder: {
        id: 'sms_reminder',
        type: 'send-sms',
        config: {message: 'Thanks for booking! See you soon.'}
      }
    },
    edges: [{id: 'e_booked', source: 'tag_booked', target: 'sms_reminder'}],
    dispositionEntries: {SUCCESS: 'tag_booked'}
  })
};

fetch('https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'nodes' => [
        'tag_booked' => [
                'id' => 'tag_booked',
                'type' => 'add-tag',
                'config' => [
                                'tags' => [
                                                                'booked_via_ai'
                                ]
                ]
        ],
        'sms_reminder' => [
                'id' => 'sms_reminder',
                'type' => 'send-sms',
                'config' => [
                                'message' => 'Thanks for booking! See you soon.'
                ]
        ]
    ],
    'edges' => [
        [
                'id' => 'e_booked',
                'source' => 'tag_booked',
                'target' => 'sms_reminder'
        ]
    ],
    'dispositionEntries' => [
        'SUCCESS' => 'tag_booked'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow"

	payload := strings.NewReader("{\n  \"nodes\": {\n    \"tag_booked\": {\n      \"id\": \"tag_booked\",\n      \"type\": \"add-tag\",\n      \"config\": {\n        \"tags\": [\n          \"booked_via_ai\"\n        ]\n      }\n    },\n    \"sms_reminder\": {\n      \"id\": \"sms_reminder\",\n      \"type\": \"send-sms\",\n      \"config\": {\n        \"message\": \"Thanks for booking! See you soon.\"\n      }\n    }\n  },\n  \"edges\": [\n    {\n      \"id\": \"e_booked\",\n      \"source\": \"tag_booked\",\n      \"target\": \"sms_reminder\"\n    }\n  ],\n  \"dispositionEntries\": {\n    \"SUCCESS\": \"tag_booked\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"nodes\": {\n    \"tag_booked\": {\n      \"id\": \"tag_booked\",\n      \"type\": \"add-tag\",\n      \"config\": {\n        \"tags\": [\n          \"booked_via_ai\"\n        ]\n      }\n    },\n    \"sms_reminder\": {\n      \"id\": \"sms_reminder\",\n      \"type\": \"send-sms\",\n      \"config\": {\n        \"message\": \"Thanks for booking! See you soon.\"\n      }\n    }\n  },\n  \"edges\": [\n    {\n      \"id\": \"e_booked\",\n      \"source\": \"tag_booked\",\n      \"target\": \"sms_reminder\"\n    }\n  ],\n  \"dispositionEntries\": {\n    \"SUCCESS\": \"tag_booked\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/workflow")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"nodes\": {\n    \"tag_booked\": {\n      \"id\": \"tag_booked\",\n      \"type\": \"add-tag\",\n      \"config\": {\n        \"tags\": [\n          \"booked_via_ai\"\n        ]\n      }\n    },\n    \"sms_reminder\": {\n      \"id\": \"sms_reminder\",\n      \"type\": \"send-sms\",\n      \"config\": {\n        \"message\": \"Thanks for booking! See you soon.\"\n      }\n    }\n  },\n  \"edges\": [\n    {\n      \"id\": \"e_booked\",\n      \"source\": \"tag_booked\",\n      \"target\": \"sms_reminder\"\n    }\n  ],\n  \"dispositionEntries\": {\n    \"SUCCESS\": \"tag_booked\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "workflow": {
    "locationId": "loc_abc123",
    "campaignId": "cmp_123",
    "campaignConfig": {
      "callbackMode": "ai"
    },
    "nodes": {
      "tag_booked": {
        "id": "tag_booked",
        "type": "add-tag",
        "config": {
          "tags": [
            "booked_via_ai"
          ]
        }
      },
      "sms_reminder": {
        "id": "sms_reminder",
        "type": "send-sms",
        "config": {
          "message": "Thanks for booking! See you soon."
        }
      }
    },
    "edges": [
      {
        "id": "e_booked",
        "source": "tag_booked",
        "target": "sms_reminder"
      }
    ],
    "dispositionEntries": {
      "SUCCESS": "tag_booked"
    },
    "version": 4,
    "createdAt": "2026-07-01T09:15:22.000Z",
    "updatedAt": "2026-07-14T16:04:11.000Z"
  }
}

{
  "success": false,
  "error": "VALIDATION",
  "message": "Something here doesn't look right. Please check it and try again."
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Please sign in to continue."
}

{
  "success": false,
  "error": "InsufficientScope",
  "message": "This access key does not allow this action. Please ask your account admin to change its permissions.",
  "requiredScope": "campaign_workflows:write"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "We couldn't find that. It may have been moved or deleted."
}

{
  "success": false,
  "error": "CONFLICT",
  "message": "This changed while you were working on it. Please refresh and try again."
}

{
  "success": false,
  "error": "TooManyRequests",
  "message": "That's a lot at once. Please wait a moment and try again."
}

{
  "success": false,
  "error": "Internal",
  "message": "Something went wrong on our side. Please try again in a moment.",
  "ref": "3f2b8c1e-7d4a-4f8e-9b6a-2c1d0e5f7a9b"
}

Developer setup

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Caller ID

Voices

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

Replace the entire workflow

Authorizations

Path Parameters

Query Parameters

Body

Response