> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teamfollowup.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the public API base URL: https://api.teamfollowup.ai/api.
> Authenticate public API requests with Authorization: Bearer YOUR_API_KEY.
> Use product-owned terms: agents, campaigns, projects (GoHighLevel sub-accounts), contacts, calls, outcomes, skills, cadences, phone numbers.
> Scope requests by locationId rather than projectName.
> Read the guide linked from each API reference group before recommending an endpoint.

# Quickstart

> Create an agent, give it a number, hear it call you, and switch it live. Five requests, and every new lead in the sub-account gets a call within a minute of the trigger tag landing.

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](/concepts/projects).
* An API key with the `agents:write`, `phone_numbers:write` and `calls:write`
  scopes, created under **API Keys** in the dashboard. See
  [Authentication](/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](/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](/api-reference/projects/list-campaign-projects)
returns the projects that can hold campaigns. Pick the one you want.

```http theme={"dark"}
GET /api/agent-builder/projects
```

Copy the `locationId` of your project.

## Step 2: Create the agent and its campaign

One request to [Create agent](/api-reference/agents/create-agent) creates the
agent, its prompt, and the campaign that decides who it calls and when.

```http theme={"dark"}
POST /api/agent-builder/agents
```

```json theme={"dark"}
{
  "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](/agents/agent-types). |
| `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](/agents/prompt).                                                               |
| `campaign.activeTags`   | The trigger. A contact in the sub-account that gets this tag enters the campaign. See [Who gets called](/campaigns/audience).                 |
| `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](/campaigns/dispatch-modes).                                        |

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](/api-reference/phone-numbers/search-agent-phone-numbers)
for a local number, then [buy it](/api-reference/phone-numbers/buy-agent-phone-number)
for the agent.

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

```http theme={"dark"}
POST /api/agent-builder/agents/{id}/phone-numbers
```

```json theme={"dark"}
{ "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](/phone-numbers/overview).

## Step 4: Hear it call you

Before a lead hears the agent, you should. Call
[Create test call](/api-reference/agents/create-test-call):

```http theme={"dark"}
POST /api/agent-builder/agents/{id}/test-call
```

```json theme={"dark"}
{ "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:

```http theme={"dark"}
GET /api/call-history/by-call-id/{callId}
```

You get the transcript, the outcome, and the details the agent captured. See
[Test your agent](/agents/test-your-agent) for the browser test and the full
campaign test run.

## Step 5: Switch it live

One field on [Update campaign](/api-reference/agents/update-campaign):

```http theme={"dark"}
PATCH /api/agent-builder/agents/{id}/campaign
```

```json theme={"dark"}
{ "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](/campaigns/calling-window).

## What you built

* An **agent** that knows what to say. See [What an agent is](/agents/overview).
* A **campaign** that decides who to call and when. See
  [What a campaign is](/campaigns/overview).
* A **number** the calls come from.

## Next steps

* [Write a skill](/skills/writing-a-skill) to handle the price objection the
  way you would.
* [What your agent records](/agents/outcomes) to see what each call writes
  back to the CRM.
* [Campaign workflows](/campaign-workflows/overview) to tag, move and notify
  on each outcome.
* [Set up rebilling for a sub-account](/billing/set-up-rebilling) to charge
  the client for the calls you just set running.
* [Connect an AI assistant](/mcp-actions) to run all of this by talking to it.