# 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": "geral@tuclinica.co"
        }
      ]
    }
  ]
}
```

## 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": "geral@tuclinica.co",
      "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": "geral@tuclinica.co",
        "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.
