Block Slot

This endpoint allows you to block a time slot in one or more calendars, without creating a traditional appointment.

🔹 Endpoint Details

POST /api/v1/appointments/block-slot

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Structure

Required Fields

Field	Type	Required	Description	Example
start	string (ISO 8601)	Yes	Start time of the block in ISO 8601 format (UTC).	"2025-05-20T14:00:00Z"
calendarIds	array of string (UUID)	No	IDs of related calendars to block. Each must be a valid UUID.	["123e4567-e89b-12d3-a456-426614174000"]

Optional Fields

Field	Type	Required	Description	Example
end	string (ISO 8601)	No	End time of the block in ISO 8601 format (UTC). Must be after start.	"2025-05-20T15:00:00Z"
title	string	No	Title for the block slot.	"Maintenance Window"
origin	string	No	Source/platform where the block was created (e.g., "web").	"web"
externalId	string	No	External identifier for the block slot.	"EXT-BLOCK-123"
description	string	No	Detailed description of the block slot.	"Reserved for system maintenance"
extraFields	object	No	Additional custom fields for the block slot.	{ "reason": "maintenance" }
lang	string	No	Language code for the block slot.	"en"
serviceId	string (UUID)	No	Associated service	-

🧩 Request Examples

Basic Block

curl -X POST "https://openapi.onlive.site/api/v1/appointments/block-slot" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "start": "2025-05-20T14:00:00Z",
  "calendarIds": [
    "af6c6be0-689a-4cf3-a8c8-550dd97b3a6b"
  ]
}'

Comprehensive Block

curl -X POST "https://openapi.onlive.site/api/v1/appointments/block-slot" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "start": "2025-05-20T14:00:00Z",
  "end": "2025-05-20T15:00:00Z",
  "calendarIds": [
    "af6c6be0-689a-4cf3-a8c8-550dd97b3a6b"
  ],
  "title": "Maintenance Window",
  "description": "Reserved for system maintenance",
  "origin": "web",
  "externalId": "EXT-BLOCK-123",
  "extraFields": {
    "reason": "maintenance"
  },
  "lang": "en",
  "serviceId": "01392598-e4b2-4810-ac7c-8c9cf4286a26"
}'

📤 Response Format

Success Response (200 OK)

{
  "id": "ae5bad38-402b-4766-aed9-28dc7d9fdbf4"
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "end",
      "message": "end time must be after start time"
    }
  ]
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to block slot"
}

409 Conflict

{
  "statusCode": 409,
  "message": "Failed: Appointment time slot busy"
}

📘 Notes

• The organizationId is automatically set from your authentication credentials.
• All times must be in ISO 8601 format and UTC timezone.
• The block can be applied to one or more calendars by specifying their IDs.
• If end is not specified, the block will be indefinite or as per backend logic.
• You may provide additional fields such as title, description, origin, externalId, extraFields, and lang for better context and traceability.

✅ Common Use Cases

• Reserve unavailable time in a calendar.
• Block time slots for maintenance or internal events.
• Prevent bookings at specific times.

🔍 Validation Rules

1. Time Validation

   • If specified, end must be after start.
   • Times must be in the future.

2. Calendar Validation

   • Calendar IDs must be valid UUIDs.
   • The interval must not overlap with other blocks, unless allowed by business logic.