Docfav Public API

Welcome to the Docfav Public API. This API allows you to integrate your system with Docfav to manage appointments, clients, availability, and more.

Base URLhttps://www.docfav.com/api-connector/v1

Response Format

All responses follow this structure:

{"data": { ... },
  "errors": [],
  "meta": {"timestamp": "2026-02-05T12:00:00+00:00",
    "api_version": "v1"
  }
}

Timestamps

All datetime values in the API are in UTC (ISO 8601 format). Use the timezone field from staff calendars to convert to local time when displaying to users.

Authentication

The API uses API Key authentication. Include your API key in the X-Api-Key header of each request.

Request Example

curl -H "X-Api-Key: df_pk_your_api_key" \
  https://www.docfav.com/api-connector/v1/me

Getting your API Key

Log in to your Docfav account
Go to Settings → API
Create a new API Key
Copy and save the key securely (it's only shown once)

Important: Never share your API key or include it in client-side code. Treat your API key like a password.

Scopes

API keys have specific permissions (scopes) that determine which endpoints they can access:

Scope	Description
`user:read`	Access to user information
`profiles:read`	Access to professional profiles
`backofficeclinics:read`	Access to back office clinic information
`staff:read`	Access to staff and staff calendars information
`services:read`	Access to services catalog
`clients:read`	Access to client information and search
`clients:write`	Create and update clients
`appointments:read`	Access to appointments and availability
`appointments:write`	Create and update appointments

Rate Limiting

API requests are rate limited to ensure service stability. Limits depend on your plan.

Response Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per hour
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

If you exceed the limit, you'll receive a 429 Too Many Requests error. Wait for the time indicated in the Retry-After header.

Error Codes

The API uses standard HTTP codes to indicate request results.

Code	Error	Description
400	`VALIDATION_ERROR`	Invalid request parameters
401	`INVALID_API_KEY`	Invalid or missing API key
401	`API_KEY_REVOKED`	The API key has been revoked
401	`API_KEY_EXPIRED`	The API key has expired
403	`INSUFFICIENT_SCOPES`	The API key lacks required permissions
403	`CLINIC_MANAGER_ACCESS_DENIED`	The user is not a manager of the requested clinic
403	`IP_NOT_ALLOWED`	Access denied from this IP address
404	`NOT_FOUND`	Resource not found
409	`CLIENT_EMAIL_EXISTS`	A client with this email already exists
429	`RATE_LIMIT_EXCEEDED`	Request rate limit exceeded
500	`INTERNAL_ERROR`	Internal server error
503	`API_DISABLED`	The API is temporarily disabled

Error Format

{"data": null,
  "errors": [
    {"code": "INVALID_API_KEY",
      "message": "Invalid API key"
    }
  ],
  "meta": {"timestamp": "2026-02-05T12:00:00+00:00",
    "api_version": "v1"
  }
}

User & Profiles

Endpoints to access user and profile information.

GET /api-connector/v1/me

Get the authenticated user information.

Scope: user:read

Response Example

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "fullname": "John Doe",
    "firstname": "John",
    "lastname": "Doe",
    "timezone": "Europe/Madrid",
    "locale": "es_ES",
    "country_code": "ES",
    "status": "active"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

GET /api-connector/v1/profiles

List all professional profiles for the authenticated user.

Scope: profiles:read

Response Example

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "professional",
      "back_office_clinic_id": "550e8400-e29b-41d4-a716-446655440002",
      "last_selected": true
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Clinics

Endpoints to access back office clinic information.

GET /api-connector/v1/backofficeclinics

List all back office clinics associated with the authenticated user.

Scope: backofficeclinics:read

Response Example

{
  "data": [
    {
      "id": "6edafcff-732d-4cce-8f16-f0d50d2b22b2",
      "name": "Central Clinic",
      "business_name": "Central Clinic S.L.",
      "vat_number": "B12345678",
      "address": "Main Street 1",
      "city": "Madrid",
      "zip_code": "28001",
      "has_logo": true,
      "subscription_status": "active"
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}

Get details of a specific back office clinic.

Scope: backofficeclinics:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic

Response Example

{
  "data": {
    "id": "6edafcff-732d-4cce-8f16-f0d50d2b22b2",
    "name": "Central Clinic",
    "business_name": "Central Clinic S.L.",
    "vat_number": "B12345678",
    "issuer_type": "company",
    "address": "Main Street 1",
    "city": "Madrid",
    "zip_code": "28001",
    "has_logo": true,
    "custom_email": "[email protected]",
    "default_appointments_behaviour": "confirmed",
    "subscription_status": "active"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Calendars

Endpoints to access calendars (physical locations where appointments occur).

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/calendars

List all calendars for a clinic. A calendar represents a physical location.

Scope: backofficeclinics:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic

Response Example

{
  "data": [
    {
      "id": "6e8e058e-f01b-454b-8d49-77589dadc7bd",
      "name": "Centro Getxo",
      "address": "Getxo, España",
      "city": "Getxo",
      "zip_code": "48993",
      "type": "onsite",
      "is_active": true
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Staff

Endpoints to access staff members and their calendars.

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/staff

List all staff members for a clinic.

Scope: staff:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic

Response Example

{
  "data": [
    {
      "id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "name": "Pedro",
      "surname": "García",
      "fullname": "Pedro García",
      "email": "[email protected]",
      "is_active": true
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/staffcalendars

List staff calendars for a clinic. A staff calendar links a staff member to a calendar with specific settings. Supports optional filtering by calendar or staff.

Scope: staff:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`calendar_id`	string (UUID)	query	No	Filter by calendar UUID
`staff_id`	string (UUID)	query	No	Filter by back office staff UUID
`limit`	integer	query	No	Max results to return (default: 100)
`offset`	integer	query	No	Number of results to skip (default: 0)
`order_by`	string	query	No	Sort field and direction (default: "email.asc")

Response Example

{
  "data": [
    {
      "id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "back_office_staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "calendar_id": "6e8e058e-f01b-454b-8d49-77589dadc7bd",
      "email": "[email protected]",
      "telephone": "+34600000000",
      "slot_duration": 15,
      "is_active": true,
      "timezone": "Europe/Madrid"
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Services

Endpoints to access the services catalog.

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/services

List all services for a clinic.

Scope: services:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic

Response Example

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Fisioterapia",
      "price": 5000,
      "duration": 30,
      "color": "#4CAF50",
      "is_active": true,
      "vat_rate": 21
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Clients

Endpoints to list, search, create and retrieve clients.

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/clients

List all clients for a clinic with pagination, filtering and sorting.

Scope: clients:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`limit`	integer	query	No	Max results to return (default: 10, max: 100)
`offset`	integer	query	No	Number of results to skip (default: 0)
`order_by`	string	query	No	Sort field and direction, e.g. "name.asc", "created_at.desc" (default: "name.asc")
`gender`	string	query	No	Filter by gender: "male", "female"
`min_age`	string	query	No	Minimum age filter (e.g., "18")
`max_age`	string	query	No	Maximum age filter (e.g., "65")
`activity_from`	string (YYYY-MM-DD)	query	No	Filter clients active from this date
`activity_to`	string (YYYY-MM-DD)	query	No	Filter clients active until this date

Response Example

{
  "data": {
    "clients": [
      {
        "id": "68b70480-e924-4841-8038-e2e695971ff6",
        "client_number": 1234,
        "firstname": "Carlos",
        "lastname": "Garcia",
        "fullname": "Carlos Garcia",
        "email": "[email protected]",
        "phone": "+34600000000",
        "gender": "male",
        "date_of_birth": { "dayOfBirth": "15", "monthOfBirth": "03", "yearOfBirth": "1990" },
        "address": "Calle Mayor 1",
        "city": "Madrid",
        "province": "Madrid",
        "post_code": "28001",
        "country_code": "ES",
        "id_card": "12345678A",
        "note": "Paciente habitual",
        "tags": ["vip"],
        "is_active": true,
        "is_company": false,
        "walk_in": false,
        "receive_reminders": true,
        "receive_campaigns": true,
        "has_photo": false,
        "created_at": "2026-01-15T10:00:00+00:00"
      }
    ],
    "meta": {
      "limit": 10,
      "offset": 0,
      "total": 156
    }
  },
  "errors": [],
  "meta": { "timestamp": "2026-03-04T12:00:00+00:00", "api_version": "v1" }
}

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/clients/{clientId}

Get details of a specific client by ID.

Scope: clients:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`clientId`	string (UUID)	path	Yes	UUID of the client

Response Example

{
  "data": {
    "id": "68b70480-e924-4841-8038-e2e695971ff6",
    "client_number": 1234,
    "firstname": "Carlos",
    "lastname": "García",
    "fullname": "Carlos García",
    "email": "[email protected]",
    "phone": "+34600000000",
    "gender": "male",
    "date_of_birth": { "dayOfBirth": "15", "monthOfBirth": "03", "yearOfBirth": "1990" },
    "address": "Calle Mayor 1",
    "city": "Madrid",
    "province": "Madrid",
    "post_code": "28001",
    "country_code": "ES",
    "id_card": "12345678A",
    "note": "Paciente habitual",
    "tags": ["vip"],
    "is_active": true,
    "is_company": false,
    "walk_in": false,
    "receive_reminders": true,
    "receive_campaigns": true,
    "has_photo": false,
    "created_at": "2026-01-15T10:00:00+00:00"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/clients/autocomplete

Search clients by name, surname, email, phone or ID card. Supports partial and accent-insensitive matching.

Scope: clients:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`keyword`	string	query	Yes	Search query (name, surname, email, phone, or ID card)
`limit`	integer	query	No	Max results to return (default: 20)
`offset`	integer	query	No	Number of results to skip (default: 0)
`order_by`	string	query	No	Sort field and direction (e.g. name.asc)

Response Example

{
  "data": [
    {
      "id": "68b70480-e924-4841-8038-e2e695971ff6",
      "fullname": "Carlos García",
      "email": "[email protected]",
      "telephone": "+34600000000",
      "client_number": 1234
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

POST /api-connector/v1/backofficeclinics/{backOfficeClinicId}/clients

Create a new client.

Scope: clients:write

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`name`	string	body	No	Client first name
`surname`	string	body	No	Client last name
`email`	string	body	No	Client email address
`telephone`	string	body	No	Client phone number
`walk_in`	boolean	body	No	Is walk-in client (default: false)

Request Body

{
  "name": "Carlos",
  "surname": "García",
  "email": "[email protected]",
  "telephone": "+34600000000"
}

Response Example

{
  "data": {
    "id": "68b70480-e924-4841-8038-e2e695971ff6",
    "client_number": 1234,
    "name": "Carlos",
    "surname": "García",
    "fullname": "Carlos García",
    "email": "[email protected]",
    "telephone": "+34600000000"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Availability

Endpoints to check availability and occupied time slots.

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/calendars/{calendarId}/schedules

Get staff working hours (schedules) for a date range. Returns day offs and time offs as well.

Scope: staff:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`calendarId`	string (UUID)	path	Yes	UUID of the calendar
`start_date`	string (YYYY-MM-DD)	query	Yes	Start date
`end_date`	string (YYYY-MM-DD)	query	No	End date (defaults to start_date)

Response Example

{
  "data": [
    {
      "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "name": "Pedro García",
      "schedules": [
        {
          "day": "THURSDAY",
          "date": "2026-02-05",
          "type": "REGULAR_DAY",
          "hours": [
            { "start": "08:00", "end": "14:00", "type": "WORKING_DAY" },
            { "start": "16:00", "end": "20:00", "type": "WORKING_DAY" }
          ]
        }
      ]
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/calendars/{calendarId}/occupied

Get all occupied time slots: appointments, time reservations, group reservations, day offs, and working hours.

Scope: appointments:read + staff:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`calendarId`	string (UUID)	path	Yes	UUID of the calendar
`start_date`	string (YYYY-MM-DD)	query	Yes	Start date
`end_date`	string (YYYY-MM-DD)	query	Yes	End date
`staff_calendar_id`	string (UUID)	query	No	Filter by staff calendar

Response Example

{
  "data": [
    {
      "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "name": "Pedro García",
      "working_hours": [
        { "date": "2026-02-05", "from": "08:00", "to": "20:00", "type": "WORKING_DAY" }
      ],
      "day_offs": [],
      "time_offs": [],
      "appointments": [
        {
          "id": "31bd18a6-52be-4ad3-9b9f-78b684fc6f2a",
          "from": "2026-02-05T17:00:00Z",
          "to": "2026-02-05T17:30:00Z",
          "behaviour": "confirmed",
          "client_id": "68b70480-e924-4841-8038-e2e695971ff6",
          "service_name": "Fisioterapia"
        }
      ],
      "time_reservations": [
        {
          "id": "ac14f29b-89f0-4d16-873c-772dae27650f",
          "from": "2026-02-05T13:00:00Z",
          "to": "2026-02-05T14:00:00Z",
          "reason": "Lunch break"
        }
      ],
      "group_reservations": []
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/calendars/{calendarId}/check-availability

Check if a specific time slot is available. Returns conflicts if not available.

Scope: appointments:read + staff:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`calendarId`	string (UUID)	path	Yes	UUID of the calendar
`from`	string (ISO 8601)	query	Yes	Start datetime in UTC (e.g., 2026-02-05T10:00:00Z)
`to`	string (ISO 8601)	query	Yes	End datetime in UTC
`staff_calendar_id`	string (UUID)	query	Yes	UUID of the staff calendar

Response Example

{
  "data": {
    "available": false,
    "requested": {
      "from": "2026-02-05T13:00:00Z",
      "to": "2026-02-05T14:00:00Z",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4"
    },
    "conflicts": [
      {
        "type": "time_reservation",
        "id": "ac14f29b-89f0-4d16-873c-772dae27650f",
        "from": "2026-02-05T13:00:00Z",
        "to": "2026-02-05T14:00:00Z",
        "reason": "Lunch break"
      }
    ]
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/calendars/{calendarId}/available-slots

Get all time slots with availability status. Useful for rendering a booking calendar.

Scope: appointments:read + staff:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`calendarId`	string (UUID)	path	Yes	UUID of the calendar
`start_date`	string (YYYY-MM-DD)	query	Yes	Start date
`end_date`	string (YYYY-MM-DD)	query	Yes	End date
`staff_calendar_id`	string (UUID)	query	No	Filter by staff calendar
`slot_duration`	integer	query	No	Slot duration in minutes (default: 15)
`service_duration`	integer	query	No	Service duration to check fit (default: 0)

Response Example

{
  "data": [
    {
      "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "name": "Pedro García",
      "timezone": "Europe/Madrid",
      "slot_duration": 15,
      "available_slots": [
        {
          "date": "2026-02-05",
          "day": "THURSDAY",
          "type": "REGULAR_DAY",
          "slots": [
            { "from": "2026-02-05T08:00:00Z", "to": "2026-02-05T08:15:00Z", "available": true, "hour_type": "WORKING_DAY" },
            { "from": "2026-02-05T13:00:00Z", "to": "2026-02-05T13:15:00Z", "available": false, "hour_type": "WORKING_DAY" }
          ]
        }
      ]
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Appointments

Endpoints to create and manage appointments.

GET /api-connector/v1/backofficeclinics/{backOfficeClinicId}/availability

Get appointments, time reservations, group reservations, and recurring events for a date range. Maximum range: 7 days.

Scope: appointments:read

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`start_date`	string (ISO 8601)	query	Yes	Start datetime in UTC (e.g., 2026-03-05T23:00:00Z)
`end_date`	string (ISO 8601)	query	Yes	End datetime in UTC (e.g., 2026-03-06T22:59:59Z)
`local_start_date`	string (YYYY-MM-DD)	query	No	Local start date for recurring events (e.g., 2026-03-06). Required to get recurring_events — see note below.
`local_end_date`	string (YYYY-MM-DD)	query	No	Local end date for recurring events (e.g., 2026-03-06). Required to get recurring_events — see note below.
`result_type`	string	query	No	Filter by type: "appointments", "time_reservations", "group_reservations", "recurring_events". Returns all if omitted.
`client_id`	string (UUID)	query	No	Filter appointments by client
`staff_id`	string (UUID)	query	No	Filter by staff
`calendar_id`	string (UUID)	query	No	Filter by calendar
`sale_status`	string	query	No	Filter by sale status
`limit`	integer	query	No	Max results to return (default: all)
`offset`	integer	query	No	Number of results to skip (default: 0)

Response Example

{
  "data": {
    "appointments": [
      {
        "id": "31bd18a6-52be-4ad3-9b9f-78b684fc6f2a",
        "client_id": "68b70480-e924-4841-8038-e2e695971ff6",
        "client_name": "Carlos Garcia",
        "service_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "service_name": "Consulta general",
        "calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
        "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
        "booked_from": "2026-03-06T09:00:00Z",
        "booked_to": "2026-03-06T09:30:00Z",
        "status": "confirmed",
        "sale_status": "pending",
        "note": "Primera visita",
        "price": 5000,
        "source": "backoffice"
      }
    ],
    "time_reservations": [
      {
        "id": "ac14f29b-89f0-4d16-873c-772dae27650f",
        "back_office_staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
        "name": "Lunch break",
        "booked_from": "2026-03-06T12:00:00Z",
        "booked_to": "2026-03-06T13:00:00Z",
        "note": null
      }
    ],
    "group_reservations": [],
    "recurring_events": [
      {
        "id": "b5c6d7e8-f9a0-1234-5678-9abcdef01234",
        "back_office_staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
        "name": "Weekly team meeting",
        "booked_from": "2026-03-06T08:00:00",
        "booked_to": "2026-03-06T08:30:00",
        "is_recurring_event": true,
        "original_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "timezone": "Europe/Madrid"
      }
    ]
  },
  "errors": [],
  "meta": { "timestamp": "2026-03-06T12:00:00+00:00", "api_version": "v1" }
}

IMPORTANT — Recurring Events (recurring_events):
Recurring events are generated from EventSchedules and calculated based on the clinic's local timezone, not UTC. To receive them, you MUST provide both local_start_date and local_end_date in YYYY-MM-DD format (e.g., 2026-03-06). If these parameters are omitted, the recurring_events array will be empty. The start_date/end_date parameters (UTC, ISO 8601) are used for appointments, time_reservations, and group_reservations only.

POST /api-connector/v1/backofficeclinics/{backOfficeClinicId}/appointments

Create one or more appointments.

Scope: appointments:write

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`client`	string (UUID)	body	No	Client UUID (omit for walk-in)
`timezone`	string	body	No	Timezone (default: Europe/Madrid)
`appointments`	array	body	Yes	Array of appointment objects
`appointments[].service`	string (UUID)	body	Yes	Service UUID
`appointments[].back_office_staff_calendar`	string (UUID)	body	Yes	Staff calendar UUID
`appointments[].from`	string (ISO 8601)	body	Yes	Start datetime in UTC
`appointments[].to`	string (ISO 8601)	body	Yes	End datetime in UTC
`appointments[].note`	string	body	No	Note for the appointment
`send_reminder`	boolean	body	No	Send reminder to client (default: true)
`behaviour`	string	body	No	Status: "confirmed", "pending", "cancelled" (default: confirmed)
`force`	boolean	body	No	Allow overlapping appointments (default: false)

Request Body

{
  "client": "68b70480-e924-4841-8038-e2e695971ff6",
  "timezone": "Europe/Madrid",
  "appointments": [
    {
      "service": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "back_office_staff_calendar": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "from": "2026-02-05T15:00:00Z",
      "to": "2026-02-05T15:30:00Z",
      "note": "First consultation"
    }
  ],
  "send_reminder": true,
  "behaviour": "confirmed"
}

Response Example

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "appointment_number": 12346,
      "client_id": "68b70480-e924-4841-8038-e2e695971ff6",
      "service_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "service_name": "Fisioterapia",
      "booked_from": "2026-02-05T15:00:00Z",
      "booked_to": "2026-02-05T15:30:00Z",
      "status": "confirmed",
      "note": "First consultation"
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

PUT /api-connector/v1/backofficeclinics/{backOfficeClinicId}/appointments/{appointmentId}/behaviour

Change the behaviour (status) of an appointment. Use this to confirm, cancel, mark as no-show, or revert to unconfirmed.

Scope: appointments:write

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`appointmentId`	string (UUID)	path	Yes	UUID of the appointment
`behaviour`	string	body	Yes	New status: "unconfirmed", "confirmed", "cancelled" or "no_show"
`force_capacity_increase`	boolean	body	No	Force capacity increase when reactivating a cancelled participant in a full group appointment (default: false)
`cancel_participants`	boolean	body	No	When cancelling a group appointment, also cancel all participants (default: false)

Request Body

{
  "behaviour": "cancelled"
}

Response Example

{
  "data": {
    "appointment_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "behaviour": "cancelled",
    "message": "Appointment behaviour updated successfully"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

DELETE /api-connector/v1/backofficeclinics/{backOfficeClinicId}/appointments/{appointmentId}

Delete an appointment permanently. The appointment id is obtained from the availability or create endpoints.

Scope: appointments:write

Parameters

Name	Type	In	Required	Description
`backOfficeClinicId`	string (UUID)	path	Yes	UUID of the back office clinic
`appointmentId`	string (UUID)	path	Yes	UUID of the appointment to delete

Response Example

{
  "data": {
    "message": "Appointment deleted successfully"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}