Create a calendar

Defines a bookable calendar.

timezone is required and is the calendar’s own zone. Opening hours are read in it, and a booking anchors to it. An unknown IANA zone is refused.

weeklyHours is keyed by sun, mon, tue, wed, thu, fri, sat, each an array of {start, end} in 24-hour HH:MM. A day you leave out is closed. A window that ends at or before its start is refused, so no window crosses midnight.

Other settings default to what a GoHighLevel calendar uses: slotDurationMinutes 30, slotIntervalMinutes 30, slotBufferMinutes 0, appointmentsPerSlot 1, minNoticeMinutes 180, maxDaysOut 31.

When the agent finds no free time, check minNoticeMinutes and the opening hours first. Three hours’ notice on a calendar that closes at 17:00 leaves nothing after 14:00.

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

Required API key scope: projects:write.

POST

api

native-calendar

calendars

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/native-calendar/calendars \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Consultations",
  "timezone": "America/Chicago",
  "weeklyHours": {
    "mon": [
      {
        "start": "09:00",
        "end": "17:00"
      }
    ],
    "tue": [
      {
        "start": "09:00",
        "end": "17:00"
      }
    ]
  },
  "slotDurationMinutes": 30,
  "minNoticeMinutes": 180
}'

import requests

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

payload = {
    "name": "Consultations",
    "timezone": "America/Chicago",
    "weeklyHours": {
        "mon": [
            {
                "start": "09:00",
                "end": "17:00"
            }
        ],
        "tue": [
            {
                "start": "09:00",
                "end": "17:00"
            }
        ]
    },
    "slotDurationMinutes": 30,
    "minNoticeMinutes": 180
}
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({
    name: 'Consultations',
    timezone: 'America/Chicago',
    weeklyHours: {mon: [{start: '09:00', end: '17:00'}], tue: [{start: '09:00', end: '17:00'}]},
    slotDurationMinutes: 30,
    minNoticeMinutes: 180
  })
};

fetch('https://api.teamfollowup.ai/api/native-calendar/calendars', 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/calendars",
  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([
    'name' => 'Consultations',
    'timezone' => 'America/Chicago',
    'weeklyHours' => [
        'mon' => [
                [
                                'start' => '09:00',
                                'end' => '17:00'
                ]
        ],
        'tue' => [
                [
                                'start' => '09:00',
                                'end' => '17:00'
                ]
        ]
    ],
    'slotDurationMinutes' => 30,
    'minNoticeMinutes' => 180
  ]),
  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/calendars"

	payload := strings.NewReader("{\n  \"name\": \"Consultations\",\n  \"timezone\": \"America/Chicago\",\n  \"weeklyHours\": {\n    \"mon\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ],\n    \"tue\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ]\n  },\n  \"slotDurationMinutes\": 30,\n  \"minNoticeMinutes\": 180\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/calendars")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Consultations\",\n  \"timezone\": \"America/Chicago\",\n  \"weeklyHours\": {\n    \"mon\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ],\n    \"tue\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ]\n  },\n  \"slotDurationMinutes\": 30,\n  \"minNoticeMinutes\": 180\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"name\": \"Consultations\",\n  \"timezone\": \"America/Chicago\",\n  \"weeklyHours\": {\n    \"mon\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ],\n    \"tue\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ]\n  },\n  \"slotDurationMinutes\": 30,\n  \"minNoticeMinutes\": 180\n}"

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

{
  "success": true,
  "data": {
    "_id": "cal_6b1f2a7c90",
    "locationId": "nat_fd9e2a8dd4be4396b604",
    "name": "Consultations",
    "timezone": "America/Chicago",
    "weeklyHours": {
      "mon": [
        {
          "start": "09:00",
          "end": "12:00"
        },
        {
          "start": "13:00",
          "end": "17:00"
        }
      ],
      "tue": [
        {
          "start": "09:00",
          "end": "17:00"
        }
      ],
      "wed": [
        {
          "start": "09:00",
          "end": "17:00"
        }
      ],
      "thu": [
        {
          "start": "09:00",
          "end": "17:00"
        }
      ],
      "fri": [
        {
          "start": "09:00",
          "end": "15:00"
        }
      ]
    },
    "dateOverrides": [
      {
        "date": "2026-12-25",
        "closed": true
      }
    ],
    "slotDurationMinutes": 30,
    "slotIntervalMinutes": 30,
    "slotBufferMinutes": 0,
    "appointmentsPerSlot": 1,
    "minNoticeMinutes": 180,
    "maxDaysOut": 31,
    "isActive": true,
    "createdAt": "2026-08-03T11:00:00.000Z",
    "updatedAt": "2026-09-14T08:30: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": "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 calendar.

A calendar to create, or the parts of one to change. On an update, the calendar is validated as it will be after the change.

name

string

Example:

"Consultations"

timezone

string

Required on create.

Example:

"America/Chicago"

weeklyHours

object

Opening hours by day, keyed by sun, mon, tue, wed, thu, fri, sat. Each day is a list of {start, end} in 24-hour HH:MM, and a day left out is closed. On an update it replaces all the weekly hours, so send every open day.

Show child attributes

dateOverrides

object[]

Days that differ from the weekly hours: {date, closed: true}, or {date, windows: [{start, end}]}, with date as YYYY-MM-DD. On an update it replaces the whole list.

Show child attributes

slotDurationMinutes

integer

How long an appointment lasts, in minutes. Defaults to 30.

Required range: x >= 1

slotIntervalMinutes

integer

How often a slot starts, in minutes. Defaults to 30. Less than the duration gives slots that overlap.

Required range: x >= 1

slotBufferMinutes

integer

Free time kept before and after each booking, in minutes. Defaults to 0.

Required range: x >= 0

appointmentsPerSlot

integer

How many bookings one slot can hold. Defaults to 1.

Required range: x >= 1

minNoticeMinutes

integer

How many minutes from now the first bookable slot must be. Defaults to 180.

Required range: x >= 0

maxDaysOut

integer

How many days ahead slots are offered. Defaults to 31.

Required range: x >= 1

isActive

boolean

Ignored on create and preview. On an update, false hides the calendar and stops new bookings on it. Booked appointments stay.

{key}

any

Response

The calendar as stored, with every default filled in.

success

boolean

required

data

object

required

A bookable calendar: when it is open, how long an appointment lasts, and how far ahead it will go.

Show child attributes

{key}

any

cURL

curl --request POST \
  --url https://api.teamfollowup.ai/api/native-calendar/calendars \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Consultations",
  "timezone": "America/Chicago",
  "weeklyHours": {
    "mon": [
      {
        "start": "09:00",
        "end": "17:00"
      }
    ],
    "tue": [
      {
        "start": "09:00",
        "end": "17:00"
      }
    ]
  },
  "slotDurationMinutes": 30,
  "minNoticeMinutes": 180
}'

import requests

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

payload = {
    "name": "Consultations",
    "timezone": "America/Chicago",
    "weeklyHours": {
        "mon": [
            {
                "start": "09:00",
                "end": "17:00"
            }
        ],
        "tue": [
            {
                "start": "09:00",
                "end": "17:00"
            }
        ]
    },
    "slotDurationMinutes": 30,
    "minNoticeMinutes": 180
}
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({
    name: 'Consultations',
    timezone: 'America/Chicago',
    weeklyHours: {mon: [{start: '09:00', end: '17:00'}], tue: [{start: '09:00', end: '17:00'}]},
    slotDurationMinutes: 30,
    minNoticeMinutes: 180
  })
};

fetch('https://api.teamfollowup.ai/api/native-calendar/calendars', 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/calendars",
  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([
    'name' => 'Consultations',
    'timezone' => 'America/Chicago',
    'weeklyHours' => [
        'mon' => [
                [
                                'start' => '09:00',
                                'end' => '17:00'
                ]
        ],
        'tue' => [
                [
                                'start' => '09:00',
                                'end' => '17:00'
                ]
        ]
    ],
    'slotDurationMinutes' => 30,
    'minNoticeMinutes' => 180
  ]),
  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/calendars"

	payload := strings.NewReader("{\n  \"name\": \"Consultations\",\n  \"timezone\": \"America/Chicago\",\n  \"weeklyHours\": {\n    \"mon\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ],\n    \"tue\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ]\n  },\n  \"slotDurationMinutes\": 30,\n  \"minNoticeMinutes\": 180\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/calendars")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Consultations\",\n  \"timezone\": \"America/Chicago\",\n  \"weeklyHours\": {\n    \"mon\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ],\n    \"tue\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ]\n  },\n  \"slotDurationMinutes\": 30,\n  \"minNoticeMinutes\": 180\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"name\": \"Consultations\",\n  \"timezone\": \"America/Chicago\",\n  \"weeklyHours\": {\n    \"mon\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ],\n    \"tue\": [\n      {\n        \"start\": \"09:00\",\n        \"end\": \"17:00\"\n      }\n    ]\n  },\n  \"slotDurationMinutes\": 30,\n  \"minNoticeMinutes\": 180\n}"

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

{
  "success": true,
  "data": {
    "_id": "cal_6b1f2a7c90",
    "locationId": "nat_fd9e2a8dd4be4396b604",
    "name": "Consultations",
    "timezone": "America/Chicago",
    "weeklyHours": {
      "mon": [
        {
          "start": "09:00",
          "end": "12:00"
        },
        {
          "start": "13:00",
          "end": "17:00"
        }
      ],
      "tue": [
        {
          "start": "09:00",
          "end": "17:00"
        }
      ],
      "wed": [
        {
          "start": "09:00",
          "end": "17:00"
        }
      ],
      "thu": [
        {
          "start": "09:00",
          "end": "17:00"
        }
      ],
      "fri": [
        {
          "start": "09:00",
          "end": "15:00"
        }
      ]
    },
    "dateOverrides": [
      {
        "date": "2026-12-25",
        "closed": true
      }
    ],
    "slotDurationMinutes": 30,
    "slotIntervalMinutes": 30,
    "slotBufferMinutes": 0,
    "appointmentsPerSlot": 1,
    "minNoticeMinutes": 180,
    "maxDaysOut": 31,
    "isActive": true,
    "createdAt": "2026-08-03T11:00:00.000Z",
    "updatedAt": "2026-09-14T08:30: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": "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

Create a calendar

Authorizations

Query Parameters

Body

Response