Create agent

Create a voice agent for one project from a campaign type and one or more starting capabilities. The type decides what triggers the call; the capabilities decide what the agent can do on it, and each one installs its tool, post-call fields, workflow route, and required configuration together. Optional config fields are applied during creation so API clients can provision a ready-to-use agent in one request. The operation provisions the agent, campaign, and workflow together, then rolls back known partial failures.

Required API key scope: agents:write.

POST /api/agent-builder/agents

cURL

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/agent-builder/agents \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "locationId": "loc_abc123",
  "name": "Roofing Follow Up",
  "agentType": "outreach",
  "capabilityIds": [
    "live_transfer",
    "add_tag"
  ],
  "campaign": {
    "activeTags": [
      "new_lead"
    ],
    "inactiveTags": [
      "do_not_call"
    ],
    "dialing": "s2l_pd",
    "callingWindow": {
      "days": [
        1,
        2,
        3,
        4,
        5
      ],
      "start": "09:00",
      "end": "17:00",
      "tz": "America/New_York"
    },
    "config": {
      "calendarId": "calendar_primary",
      "s2lDoubleDial": true
    }
  },
  "config": {
    "llm": {
      "generalPrompt": "# Context\nQualify the lead and book an appointment.",
      "beginMessage": "Hi, this is Sarah from Acme Roofing."
    },
    "voice": {
      "voiceId": "custom_voice_d7515c44b4aaea0ceade0a37ae",
      "temperature": 0.8,
      "speed": 1
    },
    "language": {
      "language": [
        "en-US"
      ],
      "denoisingMode": "noise-cancellation"
    },
    "analysis": {
      "outcomes": {
        "opt_out": "The lead explicitly asked not to be contacted again.",
        "callback": "The lead asked to be called back at a later time."
      },
      "fields": [
        {
          "key": "customer_name",
          "type": "text",
          "prompt": "The full name of the lead.",
          "required": true
        }
      ]
    }
  }
}'

200

default

{
  "success": true,
  "idempotentReplay": true,
  "agent": {
    "id": "agent_1ffdb9717444d0e77346838911",
    "agentId": "agent_1ffdb9717444d0e77346838911",
    "agentType": "outreach",
    "name": "Roofing Follow Up",
    "isActive": true,
    "hasCustomPrompt": true,
    "platformFieldNames": [
      "call_summary",
      "callback"
    ],
    "campaign": {
      "id": "cmp_123",
      "name": "Roofing Follow Up",
      "system": "appointment_booking",
      "agentType": "appointment_booking",
      "dialing": "s2l_pd",
      "active": false,
      "isActive": false,
      "type": "s2l_pd",
      "activeTags": [
        "new_lead"
      ],
      "inactiveTags": [
        "do_not_call"
      ],
      "callingWindow": null,
      "config": {
        "cadenceId": "cad_123",
        "calendarId": "calendar_primary"
      },
      "fromNumbers": [
        "[phone]"
      ],
      "projectId": "proj_123",
      "locationId": "loc_abc123",
      "businessName": "Acme Roofing",
      "createdAt": "2026-07-08T10:00:00.000Z",
      "updatedAt": "2026-07-08T10:00:00.000Z"
    },
    "config": {
      "agent": {
        "agentName": "Roofing Follow Up"
      },
      "llm": {
        "beginMessage": "Hi, this is Sarah from Acme Roofing.",
        "generalPrompt": "# Context\nQualify the lead and book an appointment."
      },
      "voice": {
        "voiceId": "custom_voice_d7515c44b4aaea0ceade0a37ae",
        "ambientSound": null,
        "ambientSoundVolume": 0.75,
        "temperature": 0.8,
        "speed": 1
      },
      "interaction": {
        "enableBackchannel": true,
        "backchannelFrequency": 0.6,
        "backchannelWords": [
          "yeah",
          "got it"
        ]
      },
      "language": {
        "language": "en-US",
        "denoisingMode": "noise-cancellation"
      },
      "analysis": {
        "outcomes": {
          "opt_out": "The lead explicitly asked not to be contacted again.",
          "callback": "The lead asked to be called back at a later time.",
          "human_needed": "A human team member needs to review or follow up.",
          "asked_for_info": "The lead asked to receive additional information."
        },
        "fields": [
          {
            "key": "customer_name",
            "type": "text",
            "prompt": "The full name of the lead.",
            "required": true
          }
        ],
        "locked": [
          "call_summary",
          "call_successful"
        ]
      }
    },
    "createdAt": "2026-07-08T10:00:00.000Z",
    "updatedAt": "2026-07-08T10:00:00.000Z"
  }
}

Authorizations

Authorization · string · header · required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Headers

Idempotency-Key · string

Optional retry key for create-style operations. Reusing the same key with the same request returns the original result; reusing it with a different request returns 409.

Required string length: 1 - 255

Body

application/json

locationId · string · required

Must be a connected V2 project (a GHL location connected to TFU). Passing an unconnected location id returns 404 "V2 project for locationId=… not found".

Minimum string length: 1

Example:

"loc_abc123"

name · string · required

Minimum string length: 1

Example:

"Roofing Follow Up"

agentType · enum<string> · required

Campaign type returned by List agent types, which decides what triggers the call: outreach on a CRM tag, inbound on an incoming call, appointment when an appointment is booked. An unrecognised value is rejected with a 400 listing the valid types. Integrations written before this taxonomy may instead send a legacy V2 template id as system, with no agentType; that path still works and infers the type and capabilities from the template, but it is not the supported way to create an agent.

Available options: outreach, inbound, appointment

Example:

"outreach"

capabilityIds · enum<string>[]

Behaviours to install on the new agent. Required for outreach and inbound — omitting it returns a 400 reading "At least one capability is required". Silently ignored for appointment, which always starts with Appointment Booking. Every id is installed with its tool, post-call fields, workflow route, and config gate. The FIRST id additionally selects the base template the agent is cloned from, which is what the campaign reports as system; the others are installed on top of it.

Minimum array length: 1

Available options: appointment_booking, live_transfer, add_tag

Example:

["live_transfer", "add_tag"]

templateId · enum<string>

Single-capability form of capabilityIds, kept for callers written before multi-select. Ignored when capabilityIds is present.

Available options: appointment_booking, live_transfer, add_tag

Example:

"live_transfer"

campaign · object

Optional campaign fields applied during Create agent. Server-owned fields such as id, agentId, name, agentType, active, createdAt, and updatedAt are ignored — the agent starts paused and inherits its agent type from the parent request.

Show child attributes

config · object

Optional editable agent configuration accepted on create and update. Omitted fields keep their template defaults on create, or remain unchanged on update.

Show child attributes

{key} · any

Response

200

application/json

Original successful response for a replayed Idempotency-Key request.

success · boolean · required

agent · object · required

Show child attributes

idempotentReplay · boolean

True when returned from a previous successful Idempotency-Key request.