The TeleCalendar API allows you to interact with an organization in TeleCalendar. The API is RESTful and uses JSON to transport information.
\nThe main use case for interacting with a TeleCalendar organization through the API is to manipulate appointments.
\nThis documentation aims to provide comprehensive information on how developers can use the TeleCalendar API to start building integrations with TeleCalendar.
\nPlease don't hesitate to reach out if you have any questions!
\n\nEach API resource that you use will have a clearly defined path structure. This documentation contains a reference for each resource in the API.
\nBefore you can use these resources, below is the basic structure of an API resource:
\nThe TeleCalendar API path has the following structure (depending on the endpoint):
\nhttps://api.telecalendar.com/api
ORhttps://app.telecalendar.com/api
There are different approaches for making requests to our API. The command line tool cURL is easy and fast for testing our API. When you want to integrate the API into your own software, you can choose to use a general purpose REST library based on your application language. The documentation of each resource shows specific ways in which you can make request for each resource.
\nA REST API uses HTTP methods to determine which action to perform on the resource. GET, POST, PUT and DELETE are some of the common methods used in the TeleCalendar API resources. The type of method is also indicated in the resource documentation.
\nIn order to access the TeleCalendar API, you have to be an authenticated user. TeleCalendar uses HTTP authentication via Bearer (token) authorization.
\nYour TeleCalendar admin can generate and provide you with the API token that you can use. Each API token is linked to a TeleCalendar organization user.
\nOnce you have an API token, it can be passed in the header of the request to authenticate your request:
\n'Authorization: Bearer *\\'
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"API Basics","slug":"api-basics"},{"content":"Authentication","slug":"authentication"}],"owner":"39543393","collectionId":"622aa30c-6e66-4230-ba3e-907036f90cf3","publishedId":"2sAYBbe9WS","public":true,"customColor":{"top-bar":"E2E8F0","right-sidebar":"1E293B","highlight":"94a3b8"},"publishDate":"2025-09-21T15:47:24.000Z"},"item":[{"name":"Appointments","item":[{"name":"Create appointment","id":"5daa2189-ad77-455b-aa39-aafa1105c6aa","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{"content-type":true}},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {api_token}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"start\": \"2026-01-30T16:15:00.000+01:00\",\n \"eventTypeId\": 4169488,\n \"attendee\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"timeZone\": \"Europe/Amsterdam\",\n \"language\": \"nl\"\n },\n \"location\": {\n \"type\": \"integration\",\n \"integration\": \"google-meet\"\n },\n \"guests\": [\"info@telecalendar.com\"],\n \"bookingFieldsResponses\": {\n \"BEDRIJFSNAAM\": \"Business 123\"\n }\n}"},"url":"https://api.telecalendar.com/api/appointments","urlObject":{"protocol":"https","path":["api","appointments"],"host":["api","telecalendar","com"],"query":[],"variable":[]}},"response":[{"id":"9fe02019-ba76-4943-ae20-a6c2a5f06426","name":"Create appointment","originalRequest":{"method":"POST","header":[{"key":"Authorization","value":"Bearer {api_token}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"start\": \"2025-09-29T07:00:00.000Z\",\n \"eventTypeId\": 3019502,\n \"location\": {\n \"type\": \"attendeeAddress\",\n \"address\": \"herengracht 597, Amsterdam\"\n },\n \"attendee\": {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"timeZone\": \"Europe/Amsterdam\",\n \"language\": \"nl\"\n },\n \"guests\": [\"info@telecalendar.com\"],\n \"lengthInMinutes\": 30\n}"},"url":"https://api.telecalendar.com/api/appointments"},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n \"status\": \"success\",\n \"data\": {\n \"id\": 11067325,\n \"uid\": \"rTq4W3t5CDTvAAYficfyUq\",\n \"title\": \"Appointment example\",\n \"description\": \"\",\n \"hosts\": [\n {\n \"id\": 1678431,\n \"name\": \"Accountmanager Test\",\n \"email\": \"info@telecalendar.com\",\n \"timeZone\": \"Europe/Amsterdam\"\n }\n ],\n \"status\": \"accepted\",\n \"start\": \"2025-09-29T07:00:00.000Z\",\n \"end\": \"2025-09-29T07:30:00.000Z\",\n \"duration\": 30,\n \"eventTypeId\": 3019502,\n \"location\": \"herengracht 597, Amsterdam\",\n \"createdAt\": \"2025-09-21T07:44:00.857Z\",\n \"updatedAt\": \"2025-09-21T07:44:01.407Z\",\n \"metadata\": {},\n \"attendees\": [\n {\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\",\n \"timeZone\": \"Europe/Amsterdam\",\n \"language\": \"nl\",\n \"absent\": false\n },\n {\n \"name\": \"\",\n \"email\": \"info@telecalendar.com\",\n \"timeZone\": \"Europe/Amsterdam\",\n \"language\": \"en\",\n \"absent\": false\n }\n ],\n \"guests\": [\n \"info@telecalendar.com\"\n ],\n \"bookingFieldsResponses\": {\n \"email\": \"john@example.com\",\n \"name\": \"John Doe\",\n \"guests\": [\n \"info@telecalendar.com\"\n ],\n \"location\": {\n \"value\": \"attendeeInPerson\",\n \"optionValue\": \"herengracht 597, Amsterdam\"\n }\n }\n }\n}"}],"_postman_id":"5daa2189-ad77-455b-aa39-aafa1105c6aa"},{"name":"Get appointments","id":"151a7a4a-f783-40b4-b936-1f3c1db74015","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {api_token}","type":"text"}],"url":"https://api.telecalendar.com/api/appointments?status=upcoming,past&afterStart=2026-02-01T00:00:00.000Z&beforeEnd=2026-02-27T23:59:59.999Z&afterCreatedAt&beforeCreatedAt&sortStart=asc&sortEnd&sortCreated&sortUpdatedAt&take=100&skip=0","urlObject":{"protocol":"https","path":["api","appointments"],"host":["api","telecalendar","com"],"query":[{"description":{"content":"OPTIONAL
\nType: enum<string>[]
Filter bookings by status.\nIf filtering by multiple statuses, separate them with a comma.
\nAllowed values:\nupcoming,\nrecurring,\npast,\ncancelled,\nunconfirmed
\nExample:\n?status=upcoming,past
\n","type":"text/plain"},"key":"status","value":"upcoming,past"},{"description":{"content":"OPTIONAL
\nType: string\nFormat: UTC ISO 8601 datetime
Filter bookings that start after this date/time.
\nExample:\n?afterStart=2026-02-01T00:00:00.000Z
\n","type":"text/plain"},"key":"afterStart","value":"2026-02-01T00:00:00.000Z"},{"description":{"content":"OPTIONAL
\nType: string\nFormat: UTC ISO 8601 datetime
Filter bookings that end before this date/time.
\nExample:\n?beforeEnd=2026-02-27T23:59:59.999Z
\n","type":"text/plain"},"key":"beforeEnd","value":"2026-02-27T23:59:59.999Z"},{"description":{"content":"OPTIONAL
\nType: string\nFormat: UTC ISO 8601 datetime
Filter bookings created after this date/time.
\nExample:\n?afterCreatedAt=2026-02-01T00:00:00.000Z
\n","type":"text/plain"},"key":"afterCreatedAt","value":null},{"description":{"content":"OPTIONAL
\nType: string\nFormat: UTC ISO 8601 datetime
Filter bookings created before this date/time.
\nExample:\n?beforeCreatedAt=2026-02-27T23:59:59.999Z
\n","type":"text/plain"},"key":"beforeCreatedAt","value":null},{"description":{"content":"OPTIONAL
\nType: enum<string>
Sort results by start time.
\nAllowed values:\n• asc\n• desc
\nExample:\n?sortStart=asc
\n","type":"text/plain"},"key":"sortStart","value":"asc"},{"description":{"content":"OPTIONAL
\nType: enum<string>
Sort results by end time.
\nAllowed values:\n• asc\n• desc
\nExample:\n?sortEnd=desc
\n","type":"text/plain"},"key":"sortEnd","value":null},{"description":{"content":"OPTIONAL
\nType: enum<string>
Sort results by booking creation time.
\nAllowed values:\n• asc\n• desc
\nExample:\n?sortCreated=asc
\n","type":"text/plain"},"key":"sortCreated","value":null},{"description":{"content":"OPTIONAL
\nType: enum<string>
Sort results by last updated time (e.g. status change).
\nAllowed values:\n• asc\n• desc
\nExample:\n?sortUpdatedAt=desc
\n","type":"text/plain"},"key":"sortUpdatedAt","value":null},{"key":"take","value":"100"},{"key":"skip","value":"0"}],"variable":[]}},"response":[{"id":"852a391c-b18f-4be1-b41d-e15008ff4ce2","name":"Get appointments","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {api_token}","type":"text"}],"url":{"raw":"https://api.telecalendar.com/api/appointments?status=upcoming,past&afterStart=2026-02-01T00:00:00.000Z&beforeEnd=2026-02-27T23:59:59.999Z&afterCreatedAt&beforeCreatedAt&sortStart=asc&sortEnd&sortCreated&sortUpdatedAt&take=100&skip=0","protocol":"https","host":["api","telecalendar","com"],"path":["api","appointments"],"query":[{"key":"status","value":"upcoming,past","description":"OPTIONAL\n\nType: `enumContent-Type: application/json
Create appointment
\nstartType: string (ISO 8601, UTC)
Required
The start time of the booking. Must be expressed in UTC.
Example:
\n\"2024-08-13T09:00:00Z\"\n\nattendeeType: object
Required
The attendee’s details.
\nChild attributes:
\nname — string, required. Full name of attendee.email — string, required. Email of attendee.timeZone — string, required. Valid IANA time zone (e.g. \"Europe/Amsterdam\").language — string, optional. ISO language code (e.g. \"en\").bookingFieldsResponsesType: object
Optional responses to custom booking fields. (Important for EMAIL/SMS VARIABLES)
\nExample:
\n{ \"customField\": \"customValue\" }\n\neventTypeIdType: number
Required unless you provide eventTypeSlug + username (or teamSlug).
The ID of the event type being booked.
\nExample:
\n3019502\n\nguestsType: string[]
Optional list of guest emails.
\nExample:
\n[\"guest1@example.com\", \"guest2@example.com\"]\n\nlocationType: object
Optional. One of the event type’s supported locations.
\nChild attributes depend on type, for example:
\ntype — \"attendeeAddress\" | \"integration\"address — string (if type = attendeeAddress).integration — \"google-meet\" | \"zoom\" | \"office365-video\"(if type = integration).Example:
\n{ \"type\": \"attendeeAddress\", \"address\": \"Herengracht 597, Amsterdam\" }\n\nlengthInMinutesType: number
Optional. Length of the appointment in minutes.
\nIf omitted, the default event type length is used.
\nExample:
\n30\n\nType: string
The ID of the event type for which available slots should be checked.
REQUIRED
Type: string
Format: UTC ISO8601 date
Start date/time of the availability window.
REQUIRED
Type: string
Format: UTC ISO8601 date
End date/time of the availability window.
REQUIRED
Type: string
Slot duration in minutes. If the event type supports multiple possible durations, you can specify the desired duration here.
OPTIONAL
Type: string
Time zone in which the available slots should be returned.
Defaults to UTC. Example: Europe/Amsterdam.
OPTIONAL
eventTypeId — 4977046
Type: string
The ID of the TeleCalendar campaign event type to find team slots for.
REQUIRED
date — 2026-03-11
Type: string
Format: YYYY-MM-DD or DD-MM-YYYY
Any date within the target week. The endpoint searches the full Mon–Sun window.
REQUIRED
address — Palamedeestraat 38, 2026VX Haarlem
Type: string
The destination address. Used to calculate travel feasibility per account manager.
REQUIRED
maxCommuteMinutes — 60
Type: number
Override the campaign's default max commute time in minutes (max travel time between appointments).
OPTIONAL
RESPONSE
\ndate — 2026-03-11
Type: string
The normalised date from the request, returned as YYYY-MM-DD.
slots — []
Type: array
Up to 5 ranked available slots across the full Mon–Sun week, sorted by soonest start time.
slots[].eventTypeId — 4986435
Type: number
The child (host-specific) account manager event type ID used for this slot.
slots[].hostUserId — 1439196
Type: number
The user ID of the account manager assigned to this slot.
slots[].hostName — Rob Koopman
Type: string
Display name of the account manager.
slots[].start — 2026-03-10T13:00:00.000Z
Type: string
Format: UTC ISO8601. Start time of the available slot.
slots[].end — 2026-03-10T14:00:00.000Z
Type: string
Format: UTC ISO8601. End time of the available slot.
slots[].date — 2026-03-10
Type: string
The calendar date of this slot in YYYY-MM-DD. May differ from the request date as the endpoint searches the full week.
slots[].baselineTravelSeconds — 18
Type: number
Travel time in seconds between the preceding and following event without the new appointment (A→C direct). Used to compute the detour cost.
slots[].detourSeconds — 2850
Type: number
Extra travel added by inserting this slot: (A→B + B→C) - (A→C). Lower is better.
slots[].waitAtBSeconds — 18369
Type: number
Idle time the host would spend waiting at the destination before the slot starts.
slots[].checks — []
Type: array
Travel feasibility checks for the legs around this slot (before and after).
slots[].checks[].leg — before
Type: string
Enum: before, after. Which leg this check covers: travel to the slot (before) or away from it (after).
slots[].checks[].travelSeconds — 1431
Type: number
Estimated travel time in seconds for this leg.
slots[].checks[].availableSeconds — 19800
Type: number
Time buffer available for travel on this leg.
slots[].checks[].feasible — true
Type: boolean
Whether travel is feasible within the available window.
slots[].checks[].exceededMaxCommute — false
Type: boolean
Whether this leg exceeds the campaign's maxCommuteMinutes cap.
slots[].checks[].hidden — true
Type: boolean
If true, this check is a homebase anchor within 30 min and is suppressed in the UI.
OPTIONAL
slots[].checks[].conflictEvent.id — homebase-start-2026-03-10T07:30:00.000Z
Type: string
Unique event ID. IDs prefixed with homebase- are synthetic anchors from the host's home base.
slots[].checks[].conflictEvent.start — 2026-03-10T07:30:00.000Z
Type: string
Format: UTC ISO8601. Start time of the anchor event.
slots[].checks[].conflictEvent.end — 2026-03-10T07:30:00.000Z
Type: string
Format: UTC ISO8601. End time of the anchor event.
slots[].checks[].conflictEvent.location — Eosstraat, 1076DT, Amsterdam
Type: string
Address or location string of the anchor event.
slots[].checks[].conflictEvent.title — Rob Koopman - Rob Koopman
Type: string
Title of the anchor event. Not present on homebase anchors.
OPTIONAL
slots[].checks[].conflictEvent.duration — 45
Type: number
Duration of the anchor event in minutes. Not present on homebase anchors.
OPTIONAL
slots[].badges.shortestTravel — false
Type: boolean
True for the slot(s) with the lowest detourSeconds among the 5 returned.
slots[].badges.soonest — true
Type: boolean
True for the slot with the earliest start time among the 5 returned.