Get Timeslots

Overview

Returns the available appointment timeslots for a given service, address, and date. Call this endpoint before creating a booking to present valid timeslot options to your customer and to avoid scheduling conflicts. The system resolves the service zone from the provided addressId and serviceId, then queries for team availability within that zone on the given date.

Endpoint

GET /partners/timeslots/available

Authentication

Requires a valid API Key with the partner_timeslots_read permission.

Query Parameters

Parameter	Type	Required	Description
`addressId`	UUID	Yes	The customer’s service address ID. Used to determine the service zone.
`serviceId`	UUID	Yes	The service ID. Must be a valid service from the catalog.
`date`	ISO date string	Yes	The desired service date in `YYYY-MM-DD` format (Riyadh local date).

Example Request

curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/timeslots/available?addressId=bbbbbbbb-0000-0000-0000-000000000002&serviceId=dddddddd-0000-0000-0000-000000000004&date=2026-06-20" \
  -H "x-api-key: YOUR_API_KEY"

Success Response

HTTP Status: 200 OK

{
  "success": true,
  "data": {
    "date": "2026-06-20",
    "slots": [
      {
        "startAt": "09:00",
        "endAt": "12:00"
      },
      {
        "startAt": "14:00",
        "endAt": "17:00"
      }
    ]
  }
}

Response fields

Field	Type	Description
`date`	string	The requested service date (`YYYY-MM-DD`)
`slots`	array	Available timeslots for that date
`slots[].startAt`	string	Slot start time (`HH:MM` or `HH:MM:SS`, Riyadh local)
`slots[].endAt`	string	Slot end time (`HH:MM` or `HH:MM:SS`, Riyadh local)

Error Responses

HTTP Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing or invalid query parameters
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`FORBIDDEN`	Missing `partner_timeslots_read` permission

Notes

Timeslots are computed in real time based on team availability. The available slots for a given date may decrease as other bookings are created.
Always call this endpoint immediately before presenting options to the customer — do not cache results for more than a few minutes.
Use slots[].startAt and slots[].endAt directly as timeslot.startAt and timeslot.endAt in your booking creation request.
If slots is an empty array, no timeslots are available for the given combination.

GET /partners/services?addressId=... — List services available at the address (call after contacts)
POST /partners/bookings — Create a booking using the selected timeslot

Contacts

Bookings

Service Catalog

Overview

Endpoint

Authentication

Query Parameters

Example Request

Success Response

Response fields

Error Responses

Notes

​Overview

​Endpoint

​Authentication

​Query Parameters

​Example Request

​Success Response

​Response fields

​Error Responses

​Notes

​Related Endpoints

Overview

Endpoint

Authentication

Query Parameters

Example Request

Success Response

Response fields

Error Responses

Notes

Related Endpoints