Quickstart

By the end of this page one agent will call every new lead in a sub-account the moment your CRM tags them. Five requests. Everything here can also be done from the dashboard, and the pages linked from each step show where.

Prerequisites

A GoHighLevel sub-account connected as a project. In the dashboard that is Projects. See Agencies, projects and sub-accounts.
An API key with the agents:write, phone_numbers:write and calls:write scopes, created under API Keys in the dashboard. See Authentication.
A payment method on your agency wallet. Numbers and minutes are paid.
A phone you can answer.

Every request below carries the bearer header and goes to the base URL described in Conventions.

Step 1: Find the project’s locationId

Almost every request is scoped to a project by its locationId, the GoHighLevel location id. List campaign projects returns the projects that can hold campaigns. Pick the one you want.

GET /api/agent-builder/projects

Copy the locationId of your project.

Step 2: Create the agent and its campaign

One request to Create agent creates the agent, its prompt, and the campaign that decides who it calls and when.

POST /api/agent-builder/agents

{
  "locationId": "loc_9f7a123",
  "name": "Roofing Follow Up",
  "agentType": "outreach",
  "capabilityIds": ["appointment_booking"],
  "config": {
    "llm": {
      "generalPrompt": "You are Sam from Acme Roofing. You call homeowners who just asked for a roof quote on our website. Confirm what they need, answer questions about our process, and book a free inspection.",
      "beginMessage": "Hi, it's Sam from Acme Roofing. You just asked us about a roof quote, is now a bad time?"
    }
  },
  "campaign": {
    "activeTags": ["new_lead"],
    "inactiveTags": ["do_not_call"],
    "dialing": "s2l"
  }
}

Field	What you are deciding
`agentType`	`outreach` calls leads. `inbound` answers calls. `appointment` confirms bookings. See Campaign types and capabilities.
`capabilityIds`	What the agent is allowed to do on a call: `appointment_booking`, `live_transfer`, `add_tag`. Required for `outreach` and `inbound`.
`config.llm`	The prompt and the first line the agent says. See The prompt.
`campaign.activeTags`	The trigger. A contact in the sub-account that gets this tag enters the campaign. See Who gets called.
`campaign.inactiveTags`	The exit. A contact with this tag is never called by this campaign.
`campaign.dialing`	`s2l` calls the moment the tag lands. See Speed to lead and power dialer.

The response is the agent, with its id, the config as stored, and the campaign under campaign. The campaign is created paused, with active: false. Nothing dials yet. If part of the setup could not be applied, partialFailures says which part. Keep the agent id. Every request below uses it.

Step 3: Give it a number

The campaign needs a caller ID. Search agent phone numbers for a local number, then buy it for the agent.

GET /api/agent-builder/agents/{id}/phone-numbers/search?areaCode=415&countryCode=US

POST /api/agent-builder/agents/{id}/phone-numbers

{ "phoneNumber": "+14155550100" }

Buying is a paid action. The number lands in your agency’s pool and on the campaign’s fromNumbers. If you already own numbers in Twilio, attach one of those instead. See Phone numbers and caller ID.

Step 4: Hear it call you

Before a lead hears the agent, you should. Call Create test call:

POST /api/agent-builder/agents/{id}/test-call

{ "fromNumber": "+14155550100", "toNumber": "+14155550199" }

Your phone rings from the campaign’s number and the agent runs its prompt. Add a contact object with stand-in lead details if you want the prompt’s variables filled in. The response carries the callId. When you hang up, read the record:

GET /api/call-history/by-call-id/{callId}

You get the transcript, the outcome, and the details the agent captured. See Test your agent for the browser test and the full campaign test run.

Step 5: Switch it live

One field on Update campaign:

PATCH /api/agent-builder/agents/{id}/campaign

{ "active": true }

From now on, tag a contact new_lead in the sub-account and the agent calls them, inside the campaign’s calling window. The response carries callingWindow. If the default hours do not suit the business, set them before you go live. See Calling window.

What you built

An agent that knows what to say. See What an agent is.
A campaign that decides who to call and when. See What a campaign is.
A number the calls come from.

Next steps

Write a skill to handle the price objection the way you would.
What your agent records to see what each call writes back to the CRM.
Campaign workflows to tag, move and notify on each outcome.
Set up rebilling for a sub-account to charge the client for the calls you just set running.
Connect an AI assistant to run all of this by talking to it.

Start here

How it works

Agents

Split Testing

Master Agent

Skills & Tools

Campaigns

Campaign Workflows

Calls

Contacts

Analytics

Billing

Power Dialer

Phone Numbers

Voices

GoHighLevel

Prerequisites

Step 1: Find the project’s locationId

Step 2: Create the agent and its campaign

Step 3: Give it a number

Step 4: Hear it call you

Step 5: Switch it live

What you built

Next steps

​Prerequisites

​Step 1: Find the project’s locationId

​Step 2: Create the agent and its campaign

​Step 3: Give it a number

​Step 4: Hear it call you

​Step 5: Switch it live

​What you built

​Next steps

Prerequisites

Step 1: Find the project’s locationId

Step 2: Create the agent and its campaign

Step 3: Give it a number

Step 4: Hear it call you

Step 5: Switch it live

What you built

Next steps