API
Appointments
Services, team and batch appointments for your calendar
# Appointments > Services, team and batch appointments for your calendar - Page: https://tbit.app/docs/api/appointments - Base URL: `https://rest-api.tbit.app/v1` - Authentication: `X-API-Key` header with your key on every request (the examples read it from the `TBIT_API_KEY` environment variable) ## Overview What you need to run your business calendar from another system: the services that get booked with who handles them, the team, and batch appointment loading. It's the same as the MCP tools list_services, list_collaborators and import_appointments, with the same field names. ## Endpoints | Method | Route | Description | | --- | --- | --- | | `GET` | `/v1/services` | The services that get booked, with who handles them | | `GET` | `/v1/collaborators` | The team: name, email, role and services they handle | | `POST` | `/v1/appointments/import` | Load up to 200 appointments in one call | ## List services Each service comes with id, name, duration_minutes, price, currency, location, active and collaborators (id, name and email of those who handle it). The id is what you send as service_id when importing appointments. Services that are rented (rooms, halls, vehicles) do not show up here. `GET /v1/services` ```bash curl "https://rest-api.tbit.app/v1/services" \ -H "X-API-Key: $TBIT_API_KEY" ``` Response: ```json { "data": [ { "id": "6a0f3c2e9b1d4a0012ab34cd", "name": "Endodoncia", "duration_minutes": 60, "price": 350000, "currency": "COP", "location": "Sede norte · Calle 72 # 7-41", "active": true, "collaborators": [ { "id": "6a0f3c2e9b1d4a0012ab0001", "name": "Geral Díaz", "email": "[email protected]" } ] } ] } ``` ## List the team Each person comes with id, name, email, role, attends_appointments (whether they attend appointments) and service_ids (the services they handle). When a person has no name loaded, name comes empty: identify them by their email. `GET /v1/collaborators` ```bash curl "https://rest-api.tbit.app/v1/collaborators" \ -H "X-API-Key: $TBIT_API_KEY" ``` Response: ```json { "data": [ { "id": "6a0f3c2e9b1d4a0012ab0001", "name": "Geral Díaz", "email": "[email protected]", "role": "ADMIN", "attends_appointments": true, "service_ids": [ "6a0f3c2e9b1d4a0012ab34cd" ] } ] } ``` ## Import appointments Send up to 200 appointments per call in appointments. Each row carries phone (with country code, for example 573001234567: the contact is looked up by phone and, if it does not exist, it is created) or contact_id (a contact that already exists: the appointment goes to that record even if it has no phone, like someone writing with a WhatsApp user; if you also send phone, it is only used for notifications), optional contact_name and email, the service (service_id or service_name, the exact name regardless of case), who attends (collaborator_id or collaborator_email; if only one person attends the service you can omit it), start in ISO 8601 (without a time zone it is read in the business time zone), optional end (by default start plus the service duration), external_id (the key of the event in your system: importing again does not duplicate) and notes. Options, all at the top level of the body: notify_customer (default false: the customer gets no confirmation; true sends it like any appointment), send_reminders (default true), release_blocks (true removes that person's blocks that overlap the appointment), on_existing (skip or update: if an appointment with the same external_id already exists, it leaves it as is or moves it without telling anyone) and dry_run (true validates everything and says what it would do, without writing anything). Always start with dry_run. The response says per row what happened: status is created, updated, skipped or failed (would_create or would_update with dry_run), with appointment_id, contact_id and, if it failed, error with the reason in words (“Andrés does not handle Endodoncia; it is handled by: Geral Díaz.”). One bad row does not stop the others. Save import_id: it is what you need to undo. `POST /v1/appointments/import` ```bash curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "dry_run": true, "appointments": [ { "phone": "573001234567", "contact_name": "Ana Pérez", "service_name": "Endodoncia", "collaborator_email": "[email protected]", "start": "2026-11-20T10:00", "external_id": "gcal-7f3k2" } ] }' ``` Response: ```json { "data": { "import_id": null, "dry_run": true, "created": 1, "updated": 0, "skipped": 0, "failed": 0, "results": [ { "index": 0, "external_id": "gcal-7f3k2", "status": "would_create", "contact_id": "6a0f3c2e9b1d4a0012ab9f10" } ] } } ``` ## Undo an import Send only undo_import_id with the import_id the import returned: all the appointments that import created are canceled, without telling anyone, and their external_id is free to import them again. `POST /v1/appointments/import` ```bash curl -X POST "https://rest-api.tbit.app/v1/appointments/import" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "undo_import_id": "6a1e0b7c5d4f3a0012cd5678" }' ``` Response: ```json { "data": { "import_id": "6a1e0b7c5d4f3a0012cd5678", "cancelled": 198, "already_cancelled": 2, "failed": [] } } ``` ## Rules and errors - The person has to handle that service. If not, the row fails and the error says who does handle it. - An appointment cannot overlap another of the same person, nor another row of the same batch. If it overlaps a schedule block, the row fails unless you send release_blocks: true. - A batch that cannot be read whole (empty, more than 200 rows, an unknown field in the body) responds 400 VALIDATION_ERROR and writes nothing. - A large batch can take a while: each appointment creates its order and its contact. If your batches go over 100 appointments, split them into smaller calls.What you need to run your business calendar from another system: the services that get booked with who handles them, the team, and batch appointment loading. It's the same as the MCP tools list_services, list_collaborators and import_appointments, with the same field names.
| Method | Route | Description |
|---|---|---|
| GET | /v1/services | The services that get booked, with who handles them |
| GET | /v1/collaborators | The team: name, email, role and services they handle |
| POST | /v1/appointments/import | Load up to 200 appointments in one call |
Each service comes with id, name, duration_minutes, price, currency, location, active and collaborators (id, name and email of those who handle it). The id is what you send as service_id when importing appointments. Services that are rented (rooms, halls, vehicles) do not show up here.
/v1/servicescurl "https://rest-api.tbit.app/v1/services" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/services', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/services',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/services',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/services');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "6a0f3c2e9b1d4a0012ab34cd",
"name": "Endodoncia",
"duration_minutes": 60,
"price": 350000,
"currency": "COP",
"location": "Sede norte · Calle 72 # 7-41",
"active": true,
"collaborators": [
{
"id": "6a0f3c2e9b1d4a0012ab0001",
"name": "Geral Díaz",
"email": "[email protected]"
}
]
}
]
}Each person comes with id, name, email, role, attends_appointments (whether they attend appointments) and service_ids (the services they handle). When a person has no name loaded, name comes empty: identify them by their email.
/v1/collaboratorscurl "https://rest-api.tbit.app/v1/collaborators" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/collaborators', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/collaborators',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/collaborators',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/collaborators');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "6a0f3c2e9b1d4a0012ab0001",
"name": "Geral Díaz",
"email": "[email protected]",
"role": "ADMIN",
"attends_appointments": true,
"service_ids": [
"6a0f3c2e9b1d4a0012ab34cd"
]
}
]
}Send up to 200 appointments per call in appointments. Each row carries phone (with country code, for example 573001234567: the contact is looked up by phone and, if it does not exist, it is created) or contact_id (a contact that already exists: the appointment goes to that record even if it has no phone, like someone writing with a WhatsApp user; if you also send phone, it is only used for notifications), optional contact_name and email, the service (service_id or service_name, the exact name regardless of case), who attends (collaborator_id or collaborator_email; if only one person attends the service you can omit it), start in ISO 8601 (without a time zone it is read in the business time zone), optional end (by default start plus the service duration), external_id (the key of the event in your system: importing again does not duplicate) and notes.
Options, all at the top level of the body: notify_customer (default false: the customer gets no confirmation; true sends it like any appointment), send_reminders (default true), release_blocks (true removes that person's blocks that overlap the appointment), on_existing (skip or update: if an appointment with the same external_id already exists, it leaves it as is or moves it without telling anyone) and dry_run (true validates everything and says what it would do, without writing anything). Always start with dry_run.
The response says per row what happened: status is created, updated, skipped or failed (would_create or would_update with dry_run), with appointment_id, contact_id and, if it failed, error with the reason in words (“Andrés does not handle Endodoncia; it is handled by: Geral Díaz.”). One bad row does not stop the others. Save import_id: it is what you need to undo.
/v1/appointments/importcurl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dry_run": true,
"appointments": [
{
"phone": "573001234567",
"contact_name": "Ana Pérez",
"service_name": "Endodoncia",
"collaborator_email": "[email protected]",
"start": "2026-11-20T10:00",
"external_id": "gcal-7f3k2"
}
]
}'const response = await fetch('https://rest-api.tbit.app/v1/appointments/import', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
dry_run: true,
appointments: [
{
phone: '573001234567',
contact_name: 'Ana Pérez',
service_name: 'Endodoncia',
collaborator_email: '[email protected]',
start: '2026-11-20T10:00',
external_id: 'gcal-7f3k2',
},
],
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/appointments/import',
{
dry_run: true,
appointments: [
{
phone: '573001234567',
contact_name: 'Ana Pérez',
service_name: 'Endodoncia',
collaborator_email: '[email protected]',
start: '2026-11-20T10:00',
external_id: 'gcal-7f3k2',
},
],
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/appointments/import',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'dry_run': True,
'appointments': [
{
'phone': '573001234567',
'contact_name': 'Ana Pérez',
'service_name': 'Endodoncia',
'collaborator_email': '[email protected]',
'start': '2026-11-20T10:00',
'external_id': 'gcal-7f3k2',
},
],
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/appointments/import');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'dry_run' => true,
'appointments' => [
[
'phone' => '573001234567',
'contact_name' => 'Ana Pérez',
'service_name' => 'Endodoncia',
'collaborator_email' => '[email protected]',
'start' => '2026-11-20T10:00',
'external_id' => 'gcal-7f3k2',
],
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"import_id": null,
"dry_run": true,
"created": 1,
"updated": 0,
"skipped": 0,
"failed": 0,
"results": [
{
"index": 0,
"external_id": "gcal-7f3k2",
"status": "would_create",
"contact_id": "6a0f3c2e9b1d4a0012ab9f10"
}
]
}
}Send only undo_import_id with the import_id the import returned: all the appointments that import created are canceled, without telling anyone, and their external_id is free to import them again.
/v1/appointments/importcurl -X POST "https://rest-api.tbit.app/v1/appointments/import" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"undo_import_id": "6a1e0b7c5d4f3a0012cd5678"
}'const response = await fetch('https://rest-api.tbit.app/v1/appointments/import', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
undo_import_id: '6a1e0b7c5d4f3a0012cd5678',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/appointments/import',
{
undo_import_id: '6a1e0b7c5d4f3a0012cd5678',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/appointments/import',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'undo_import_id': '6a1e0b7c5d4f3a0012cd5678',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/appointments/import');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'undo_import_id' => '6a1e0b7c5d4f3a0012cd5678',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"import_id": "6a1e0b7c5d4f3a0012cd5678",
"cancelled": 198,
"already_cancelled": 2,
"failed": []
}
}- The person has to handle that service. If not, the row fails and the error says who does handle it.
- An appointment cannot overlap another of the same person, nor another row of the same batch. If it overlaps a schedule block, the row fails unless you send release_blocks: true.
- A batch that cannot be read whole (empty, more than 200 rows, an unknown field in the body) responds 400 VALIDATION_ERROR and writes nothing.
- A large batch can take a while: each appointment creates its order and its contact. If your batches go over 100 appointments, split them into smaller calls.