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": "timezone is required"
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "calendar does not belong to this project"
}

{
  "success": false,
  "error": "TooManyRequests"
}

{
  "success": false,
  "error": "Calendar request failed."
}

{
  "success": false,
  "error": "Calendar service is unreachable."
}

Create a calendar

Defines a bookable calendar.

timezone is required and is the calendar’s own zone: opening hours are read in it, and it is what a written booking anchors to. An unknown IANA zone is refused here rather than producing an agent that offers 3am.

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 it starts is refused rather than wrapped past midnight, because a slot that crossed midnight would land under a different date than anyone expected.

Everything else has a default that matches what a GoHighLevel calendar does, so an agent behaves the same on either: slotDurationMinutes 30, slotIntervalMinutes 30, slotBufferMinutes 0, appointmentsPerSlot 1, minNoticeMinutes 180, maxDaysOut 31.

minNoticeMinutes and the opening hours are the first two settings to check when the agent reports nothing available. Three hours’ notice on a calendar that closes at 17:00 has nothing left to offer 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": "timezone is required"
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "success": false,
  "error": "calendar does not belong to this project"
}

{
  "success": false,
  "error": "TooManyRequests"
}

{
  "success": false,
  "error": "Calendar request failed."
}

{
  "success": false,
  "error": "Calendar service is unreachable."
}

Authorizations

Authorization

string

header

required

Send your API key as Authorization: Bearer YOUR_API_KEY.

Query Parameters

locationId

string

required

The sub-account this calendar belongs to. It is the only thing that identifies the tenant here, and access is re-checked against it on every call.

Body

application/json

The calendar.

A calendar to create, or the parts of one to change. On an update the MERGED calendar is validated, not the patch.

name

string

Example:

"Consultations"

timezone

string

Required on create.

Example:

"America/Chicago"

weeklyHours

object

Show child attributes

dateOverrides

object[]

Show child attributes

slotDurationMinutes

integer

Required range: x >= 1

slotIntervalMinutes

integer

Required range: x >= 1

slotBufferMinutes

integer

Required range: x >= 0

appointmentsPerSlot

integer

Required range: x >= 1

minNoticeMinutes

integer

Required range: x >= 0

maxDaysOut

integer

Required range: x >= 1

isActive

boolean

{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

Agents

Split Testing

Skills & Tools

Campaigns

Campaign Workflows

Calls

Analytics

Billing

Projects

Power Dialer

Contacts

Native Contacts

Native Calendar

Phone Numbers

Voices

GHL

Create a calendar

Authorizations

Query Parameters

Body

Response