Create Booking Service

This endpoint allows you to create a new booking service in your organization. The service defines how future appointments will be created, including duration, scheduling rules, and calendar associations.

🔹 Endpoint Details

POST /api/v1/services

🔒 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
name	string	Yes	Name of the service	"Test Drive Standard"
duration	number	Yes	Duration in minutes	30
timeBetween	number	Yes	Buffer time in minutes	30
minTimeToSchedule	number	Yes	Minimum days to book in advance	0
maxTimeToSchedule	number	Yes	Maximum days to book in advance	90
incrementTime	number	Yes	Time slot increment in minutes	30

Calendar Object Structure

When providing the calendars field in the request, each calendar object must contain the following properties:

Field	Type	Required	Description	Example
calendarId	string (UUID)	Yes	The ID of the calendar, matches with externalId	"123e4567-e89b-12d3-a456-426614174000"
active	boolean	Yes	Whether the calendar is active and available for scheduling	true
type	string	Yes	Must be either "agent" or "asset"	"agent"
restrictionDates	object	No	Custom date restrictions for this calendar	{"include": [["2025-12-25","2026-01-01"]], "exclude": [["2025-12-26","2025-12-27"]]}

Optional Fields

Field	Type	Required	Description	Default
extraFields	object	No	Additional service details	{}
deniedMultipleAppointment	boolean	No	Prevent multiple bookings	false
image	string	No	Service image URL	-
userGroupId	string	No	Associated group UUID	-
allowOverlapping	boolean	No	Allow overlapping appointments	false
hasICall	boolean	No	Enable iCall feature	false
active	boolean	No	Service availability status	true
typeId	string	No	Service type identifier	-

Associated Entities

Date Ranges

Field	Type	Required	Description
startDate	string	Yes	Start date in ISO format
endDate	string	Yes	End date in ISO format

Calendar IDs

Array of UUIDs representing calendars associated with this service.

🧩 Request Example

curl -X POST "https://openapi.onlive.site/api/v1/services/" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature" \
-d '{
  "name": "Test Drive Standard",
  "duration": 30,
  "timeBetween": 30,
  "minTimeToSchedule": 0,
  "maxTimeToSchedule": 90,
  "incrementTime": 30,
  "extraFields": {
    "area": "Barcelona",
    "city": "Mollet Del Valles",
    "street": "Avenida. Rabassaires, 22-26",
    "country": "Spain"
  },
  "deniedMultipleAppointment": false,
  "image": "https://cdn.onlive.site/assets/cupra/cupra-terramar-img1.webp",
  "userGroupId": "f329fe97-452f-4d12-aef0-f526a74569cc",
  "allowOverlapping": true,
  "hasICall": false,
  "active": true,
  "typeId": "e3fb21fb-83ef-4051-916b-a8e96effe81f",
  "dateRanges": [
    {
      "startDate": "2024-10-13T22:00:00.000Z",
      "endDate": "2025-10-14T21:59:59.000Z"
    }
  ]
}'

📤 Response Format

Successful Response (201 Created)

{
  "id": "1610c525-f19a-40d0-8cd1-03daba3d2d98",
  "createdAt": "2025-03-09T19:32:03.735Z",
  "updatedAt": "2025-03-09T19:32:06.669Z"
  // ... other fields match the request body
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "duration",
      "message": "must be a positive number"
    }
  ]
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid or missing authorization credentials"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "User is not authorized to create services"
}

📘 Notes

• The organizationId is automatically set from your authentication credentials
• Time durations (duration, timeBetween, incrementTime) are in minutes
• Scheduling windows (minTimeToSchedule, maxTimeToSchedule) are in days
• All date-time fields must be in ISO 8601 format with UTC timezone
• Calendar IDs must belong to your organization
• The typeId must reference an existing service type

✅ Common Use Cases

• 🏢 Business Services: Create standard consultation services
• 🚗 Test Drives: Configure vehicle test drive appointments
• 👥 Team Meetings: Set up recurring meeting templates
• 📅 Resource Booking: Create equipment or room booking services
• 🏥 Medical Services: Configure medical appointment types

🔍 Validation Rules

1. Time Values

   • All durations must be positive numbers
   • incrementTime must be less than or equal to duration
   • maxTimeToSchedule must be greater than minTimeToSchedule

2. Calendars

   • At least one calendar must be provided
   • All calendar IDs must be valid UUIDs
   • Calendars must belong to your organization

3. Date Ranges

   • startDate must be before endDate
   • Dates must be in valid ISO 8601 format
   • Date ranges cannot overlap

---