Skip to main content
POST
cURL

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 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".

Minimum string length: 1
Example:

"loc_abc123"

name
string
required
Minimum string length: 1
Example:

"Roofing Follow Up"

agentType
enum<string>
required

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.

Available options:
outbound,
inbound,
confirmation
Example:

"outbound"

capabilityIds
enum<string>[]

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.

Minimum array length: 1
Available options:
appointment_booking,
live_transfer,
add_tag
Example:
templateId
enum<string>
deprecated

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.

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.

config
object

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

{key}
any

Response

Original successful response for a replayed Idempotency-Key request.

success
boolean
required
agent
object
required
idempotentReplay
boolean

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