Book an appointment

Books one contact into one calendar at one time.

startTime may be epoch milliseconds, or an ISO string. An ISO string without an offset is read in the calendar’s own zone. Send an offset to use a different zone.

The slot is checked as it is claimed, not before, so two callers racing for the last seat cannot both win: the loser gets 409 Conflict. A time that is outside the hours, inside the notice window or beyond the lookahead gets 409 Conflict too.

force: true books a time the calendar does not offer, such as outside its hours or inside its notice window. A full slot is still refused. It is for a person overriding on purpose, not for a retry.

Booking stops the contact’s follow-up campaign, as a booking made on a call does, and starts the calendar’s confirmation campaign.

Cookie-auth callers must send the x-csrf-token header.

Required API key scope: projects:write.

POST

api

native-calendar

appointments

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/native-calendar/appointments \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "calendarId": "cal_6b1f2a7c90",
  "contactId": "nct_0123456789abcdef0123",
  "startTime": "2026-09-24T15:00:00.000Z",
  "title": "Roof inspection"
}'

import requests

url = "https://api.teamfollowup.ai/api/native-calendar/appointments"

payload = {
    "calendarId": "cal_6b1f2a7c90",
    "contactId": "nct_0123456789abcdef0123",
    "startTime": "2026-09-24T15:00:00.000Z"
}
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({
    calendarId: 'cal_6b1f2a7c90',
    contactId: 'nct_0123456789abcdef0123',
    startTime: '2026-09-24T15:00:00.000Z'
  })
};

fetch('https://api.teamfollowup.ai/api/native-calendar/appointments', 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/native-calendar/appointments",
  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([
    'calendarId' => 'cal_6b1f2a7c90',
    'contactId' => 'nct_0123456789abcdef0123',
    'startTime' => '2026-09-24T15:00:00.000Z'
  ]),
  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/native-calendar/appointments"

	payload := strings.NewReader("{\n  \"calendarId\": \"cal_6b1f2a7c90\",\n  \"contactId\": \"nct_0123456789abcdef0123\",\n  \"startTime\": \"2026-09-24T15:00:00.000Z\"\n}")

	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/native-calendar/appointments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"calendarId\": \"cal_6b1f2a7c90\",\n  \"contactId\": \"nct_0123456789abcdef0123\",\n  \"startTime\": \"2026-09-24T15:00:00.000Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/native-calendar/appointments")

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 = "{\n  \"calendarId\": \"cal_6b1f2a7c90\",\n  \"contactId\": \"nct_0123456789abcdef0123\",\n  \"startTime\": \"2026-09-24T15:00:00.000Z\"\n}"

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

{
  "success": true,
  "data": {
    "ok": true,
    "status": "confirmed",
    "appointmentId": "apt_7d21c0f4a1",
    "bookedStartTime": "2026-09-24T15:00:00.000Z"
  }
}

{
  "success": false,
  "error": "BadRequest",
  "message": "Something here doesn't look right. Please check it and try again."
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Please sign in to continue."
}

{
  "success": false,
  "error": "Forbidden",
  "message": "You don't have access to this. Ask your account admin if you need it."
}

{
  "success": false,
  "error": "NotFound",
  "message": "We couldn't find that. It may have been moved or deleted."
}

{
  "success": false,
  "error": "Conflict",
  "message": "This changed while you were working on it. Please refresh and try again."
}

{
  "success": false,
  "error": "TooManyRequests",
  "message": "That's a lot at once. Please wait a moment and try again."
}

{
  "success": false,
  "error": "Internal",
  "message": "Something went wrong on our side. Please try again in a moment.",
  "ref": "3f2b8c1e-7d4a-4f8e-9b6a-2c1d0e5f7a9b"
}

{
  "success": false,
  "error": "ServiceUnavailable",
  "message": "This isn't available right now. Please try again in a moment.",
  "ref": "3f2b8c1e-7d4a-4f8e-9b6a-2c1d0e5f7a9b"
}

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Query Parameters

locationId

string

required

The sub-account. Your access to it is checked on every call.

Body

application/json

The booking.

calendarId

string

required

The calendar to book on, from GET /api/native-calendar/calendars. A deleted calendar, or one on another sub-account, is refused.

Example:

"cal_6b1f2a7c90"

contactId

string

required

The contact the appointment is for, from GET /api/native-contacts. Their follow-up calls stop once it is booked.

Example:

"nct_0123456789abcdef0123"

startTime

required

Epoch milliseconds, or an ISO string. An ISO string with no offset is read in the calendar's own zone.

Example:

"2026-09-24T15:00:00.000Z"

title

string

A short name for the appointment, shown on the calendar. Empty when omitted.

Example:

"Roof inspection"

assignedUserId

string

Who it belongs to, for a diary that is split by person.

force

boolean

Book a time the calendar does not offer, such as outside its hours or inside its notice window. A full slot is still refused.

{key}

any

Response

Booked, with the time it actually took.

success

boolean

required

data

object

required

The same shape the GoHighLevel booker answers with.

Show child attributes

{key}

any

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/native-calendar/appointments \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "calendarId": "cal_6b1f2a7c90",
  "contactId": "nct_0123456789abcdef0123",
  "startTime": "2026-09-24T15:00:00.000Z",
  "title": "Roof inspection"
}'

import requests

url = "https://api.teamfollowup.ai/api/native-calendar/appointments"

payload = {
    "calendarId": "cal_6b1f2a7c90",
    "contactId": "nct_0123456789abcdef0123",
    "startTime": "2026-09-24T15:00:00.000Z"
}
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({
    calendarId: 'cal_6b1f2a7c90',
    contactId: 'nct_0123456789abcdef0123',
    startTime: '2026-09-24T15:00:00.000Z'
  })
};

fetch('https://api.teamfollowup.ai/api/native-calendar/appointments', 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/native-calendar/appointments",
  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([
    'calendarId' => 'cal_6b1f2a7c90',
    'contactId' => 'nct_0123456789abcdef0123',
    'startTime' => '2026-09-24T15:00:00.000Z'
  ]),
  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/native-calendar/appointments"

	payload := strings.NewReader("{\n  \"calendarId\": \"cal_6b1f2a7c90\",\n  \"contactId\": \"nct_0123456789abcdef0123\",\n  \"startTime\": \"2026-09-24T15:00:00.000Z\"\n}")

	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/native-calendar/appointments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"calendarId\": \"cal_6b1f2a7c90\",\n  \"contactId\": \"nct_0123456789abcdef0123\",\n  \"startTime\": \"2026-09-24T15:00:00.000Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.teamfollowup.ai/api/native-calendar/appointments")

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 = "{\n  \"calendarId\": \"cal_6b1f2a7c90\",\n  \"contactId\": \"nct_0123456789abcdef0123\",\n  \"startTime\": \"2026-09-24T15:00:00.000Z\"\n}"

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

{
  "success": true,
  "data": {
    "ok": true,
    "status": "confirmed",
    "appointmentId": "apt_7d21c0f4a1",
    "bookedStartTime": "2026-09-24T15:00:00.000Z"
  }
}

{
  "success": false,
  "error": "BadRequest",
  "message": "Something here doesn't look right. Please check it and try again."
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Please sign in to continue."
}

{
  "success": false,
  "error": "Forbidden",
  "message": "You don't have access to this. Ask your account admin if you need it."
}

{
  "success": false,
  "error": "NotFound",
  "message": "We couldn't find that. It may have been moved or deleted."
}

{
  "success": false,
  "error": "Conflict",
  "message": "This changed while you were working on it. Please refresh and try again."
}

{
  "success": false,
  "error": "TooManyRequests",
  "message": "That's a lot at once. Please wait a moment and try again."
}

{
  "success": false,
  "error": "Internal",
  "message": "Something went wrong on our side. Please try again in a moment.",
  "ref": "3f2b8c1e-7d4a-4f8e-9b6a-2c1d0e5f7a9b"
}

{
  "success": false,
  "error": "ServiceUnavailable",
  "message": "This isn't available right now. Please try again in a moment.",
  "ref": "3f2b8c1e-7d4a-4f8e-9b6a-2c1d0e5f7a9b"
}

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

Book an appointment

Authorizations

Query Parameters

Body

Response