Skip to main content

​
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

ParameterTypeRequiredDescription
addressIdUUIDYesThe customer’s service address ID. Used to determine the service zone.
serviceIdUUIDYesThe service ID. Must be a valid service from the catalog.
dateISO date stringYesThe 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": [
    {
      "startAt": "09:00",
      "endAt": "12:00"
    },
    {
      "startAt": "14:00",
      "endAt": "17:00"
    }
  ]
}
The exact shape of each timeslot object may contain additional fields depending on the scheduling engine. The fields shown are the core fields you need for booking creation.

​
Error Responses

HTTP StatusCodeDescription
400VALIDATION_ERRORMissing or invalid query parameters
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENMissing 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 the startAt and endAt values from this response directly as timeslot.startAt and timeslot.endAt in your booking creation request.
  • If an empty array is returned, no timeslots are available for the given combination.
  • GET /partners/services — List available services
  • POST /partners/bookings — Create a booking using the selected timeslot