> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecleanlife.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Timeslots

> GET /partners/timeslots/available — Get available 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

```bash theme={null}
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`

```json theme={null}
{
  "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.

***

## Related Endpoints

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