Create campaign test run

Start a test of this agent’s campaign on one contact.

The test runs the real campaign, so its call is real and its post-call workflow applies tags and CRM changes. For an inbound campaign, the tester calls in from callerPhone. Check progress with GET /api/agent-builder/agents/{id}/campaign/test-runs/{intentId}.

Before it fires, the test can ask a question instead (data.needsDecision, with nothing written): a campaign with only power dialer calls asks whether to call now (callNow), and a call outside the calling window asks whether to override it (overrideCallingWindow). Send the same request again with the answer.

Required API key scope: calls:write.

POST

api

agent-builder

agents

{id}

campaign

test-runs

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "contactId": "contact_123",
  "agentTest": false
}'

import requests

url = "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "intentId": "66a91f0b0d8f3b2b79a01f12",
    "locationId": "loc_abc123",
    "contactId": "contact_123",
    "contactCreated": true,
    "campaignId": "cmp_123",
    "activeTags": [
      "new_lead"
    ],
    "expiresAt": "2026-07-08T16:35:00.000Z"
  }
}

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Path Parameters

string

required

Agent id.

Minimum string length: 1

Query Parameters

locationId

string

Pair with campaignId; omit both for primary campaign.

Minimum string length: 1

campaignId

string

Pair with locationId; omit both for primary campaign.

Minimum string length: 1

Body

application/json

contactId

string | null

Existing contact id for outbound and appointment campaign tests: the GoHighLevel contact id, or the nct_ id on a sub-account with no CRM. The dashboard resolves this client-side. Use null for inbound dial-in tests.

Example:

"contact_123"

contact

object

API-convenience alternative to contactId: create, or reuse deduped by phone, a contact from these details when contactId is omitted. The contact is made wherever the sub-account keeps its contacts. No marker tag is applied. contactId wins when both are sent.

Show child attributes

callerPhone

string

Tester phone number for inbound dial-in tests.

Example:

"+14155559876"

agentTest

boolean

When true, run an agent-only inbound test without campaign side effects.

Example:

false

callNow

boolean

Answer to the no_speed_to_lead decision. true calls the contact now; false queues them into the campaign, where the power dialer calls them on its schedule. Leave it out until a response asks.

Example:

true

overrideCallingWindow

boolean

Answer to the calling_window decision. true calls now although the calling window does not allow a call at this time; false lets the call wait for the window. Leave it out until a response asks.

Example:

true

forceCall

boolean

Call now anyway: dial the test now, overriding whatever is in the way (a call already in progress with this number, an earlier test, the calling window). Implies callNow and overrideCallingWindow, so no question is asked. A stop on the number never needs it: every test lifts the contact's stops before it dials. One that does not come off answers TEST_STOPS_NOT_CLEARED (503).

Example:

true

{key}

any

Response

Campaign test run created, or a question to answer before it fires.

success

boolean

required

data

object

required

Option 1
Option 2

Show child attributes

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "contactId": "contact_123",
  "agentTest": false
}'

import requests

url = "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/agent-builder/agents/{id}/campaign/test-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "intentId": "66a91f0b0d8f3b2b79a01f12",
    "locationId": "loc_abc123",
    "contactId": "contact_123",
    "contactCreated": true,
    "campaignId": "cmp_123",
    "activeTags": [
      "new_lead"
    ],
    "expiresAt": "2026-07-08T16:35:00.000Z"
  }
}

Developer setup

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Caller ID

Voices

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

Create campaign test run

Authorizations

Path Parameters

Query Parameters

Body

Response