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.
Authorizations
Send your API key as Authorization: Bearer YOUR_API_KEY.
Headers
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.
1 - 255Body
Must be a V2 project: a GoHighLevel location connected to TFU, or a sub-account that keeps its contacts on the platform. A location id that matches no project returns 404 "V2 project for locationId=… not found".
1"loc_abc123"
1"Roofing Follow Up"
Campaign type selected from the values below. It decides how the campaign dials, and it is fixed for the life of the agent: outbound calls a lead after a CRM event, inbound answers incoming calls and never dials, appointment calls ahead of a booked appointment. An unrecognised value is rejected with a 400 listing the valid types. outreach is the previous spelling of outbound and is still accepted, so no existing integration breaks; it is normalised to outbound on the way in and reads back that way. 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.
outbound, inbound, confirmation "outbound"
Behaviours to install on the new agent. Required for outbound 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. add_tag needs a CRM with tags: a sub-account with TFU AI as its CRM has none and refuses it.
1appointment_booking, live_transfer, add_tag Single-capability form of capabilityIds, kept for callers written before multi-select. Ignored when capabilityIds is present. The name is a leftover: its values are capability ids, not template ids, so a caller reading the field name reaches for the wrong catalogue. Send capabilityIds — a one-element array does the same thing and says what it means.
appointment_booking, live_transfer, add_tag "live_transfer"
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.
Optional editable agent configuration accepted on create and update. Omitted fields keep their template defaults on create, or remain unchanged on update.
