Skip to main content
POST
/
api
/
agenda
/
bookings
Create Booking
curl --request POST \
  --url https://api.example.com/api/agenda/bookings \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "<string>",
  "staff_id": "<string>",
  "item_type": "<string>",
  "item_id": "<string>",
  "status": "<string>",
  "booking_date": "<string>",
  "start_time": "<string>",
  "end_time": "<string>",
  "duration": 123,
  "notes": "<string>"
}
'
{
  "booking_id": "<string>",
  "client_id": "<string>",
  "client": {
    "name": "<string>",
    "surname": "<string>",
    "phone": "<string>"
  },
  "staff_id": {},
  "staff": {
    "name": "<string>",
    "surname": "<string>"
  },
  "item_type": "<string>",
  "item_id": "<string>",
  "status": "<string>",
  "booking_date": "<string>",
  "start_time": "<string>",
  "end_time": "<string>",
  "duration": 123,
  "notes": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "401 Unauthorized": {},
  "400 Bad Request": {}
}
Creates a new booking in the system. The endpoint automatically calculates the end_time based on the provided start_time and duration if not explicitly provided.

​
Authentication

This endpoint requires authentication via Bearer token in the Authorization header or auth_token cookie. 
Authorization: Bearer YOUR_TOKEN

​
Request Body

​
client_id
string
required
ID of the client making the bookingMust be a valid user UUID (100 characters max)
​
staff_id
string
ID of the staff member assigned to this bookingOptional - can be assigned later. Must be a valid user UUID if provided.
​
item_type
string
required
Type of item being bookedAllowed values: service, pack
​
item_id
string
required
ID of the service or pack being bookedMust be a valid service or pack UUID (100 characters max)
​
status
string
default:"pending"
Initial status of the bookingAllowed values:
  • pending: Default status for new bookings
  • confirmed: Pre-confirmed booking
  • completed: Mark as completed
  • cancelled: Create as cancelled
  • no_show: Mark as no-show
​
booking_date
string
required
Date of the bookingFormat: ISO 8601 date string (e.g., 2024-03-15 or 2024-03-15T00:00:00.000Z)
​
start_time
string
required
Start time of the bookingFormat: HH:mm (24-hour format)Example: 09:30, 14:00
​
end_time
string
End time of the bookingFormat: HH:mm (24-hour format)If not provided, automatically calculated from start_time + duration
​
duration
integer
default:60
Duration of the booking in minutesUsed to calculate end_time if not explicitly providedExample: 60 for 1 hour, 90 for 1.5 hours
​
notes
string
Optional notes or special instructions for the bookingSupports text format, max length based on database TEXT type

​
Response

Returns the created booking object with related client and staff information.
​
booking_id
string
Unique identifier for the created booking (UUID)
​
client_id
string
ID of the client who made the booking
​
client
object
Client information
​
staff_id
string | null
ID of the assigned staff member
​
staff
object | null
Staff member information
​
item_type
string
Type of booked item: service or pack
​
item_id
string
ID of the service or pack being booked
​
status
string
Current booking status
​
booking_date
string
Date of the booking (ISO 8601 format)
​
start_time
string
Start time in HH:mm format
​
end_time
string
End time in HH:mm format (calculated or provided)
​
duration
integer
Duration in minutes
​
notes
string | null
Notes or special instructions
​
created_at
string
Timestamp when the booking was created
​
updated_at
string
Timestamp when the booking was last updated

​
Examples

curl -X POST 'https://api.beils.com/api/agenda/bookings' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "client-uuid-123",
    "staff_id": "staff-uuid-456",
    "item_type": "service",
    "item_id": "service-uuid-789",
    "booking_date": "2024-03-15",
    "start_time": "10:00",
    "duration": 60,
    "notes": "First time client"
  }'

​
Response Example

{
  "booking_id": "new-booking-uuid-123",
  "client_id": "client-uuid-123",
  "client": {
    "name": "María",
    "surname": "García",
    "phone": "+34 600 123 456"
  },
  "staff_id": "staff-uuid-456",
  "staff": {
    "name": "Ana",
    "surname": "López"
  },
  "item_type": "service",
  "item_id": "service-uuid-789",
  "status": "pending",
  "booking_date": "2024-03-15T00:00:00.000Z",
  "start_time": "10:00",
  "end_time": "11:00",
  "duration": 60,
  "notes": "First time client",
  "created_at": "2024-03-05T09:30:00.000Z",
  "updated_at": "2024-03-05T09:30:00.000Z"
}

​
Error Responses

​
401 Unauthorized
error
Missing or invalid authentication token
{
  "statusCode": 401,
  "statusMessage": "Unauthorized: Token is missing or invalid"
}
​
400 Bad Request
error
Invalid or missing required fieldsCommon causes:
  • Missing required fields (client_id, item_type, item_id, booking_date, start_time)
  • Invalid UUID format
  • Invalid date/time format

​
Notes

  • If end_time is not provided, it’s automatically calculated: end_time = start_time + duration
  • The calculation handles time overflow correctly (e.g., 23:30 + 60 minutes = 00:30)
  • Default duration is 60 minutes if not specified
  • Default status is pending if not specified
  • The staff_id field is optional and can be assigned later via the update endpoint
  • In production, the service/pack duration could be automatically fetched from the item record instead of requiring manual input

Build docs developers (and LLMs) love

Get started for freeTalk to us