> ## 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.

# Introduction

> What the API is, who should use it, base URL, versioning, and timezones.

## What Is the CleanLife Partner API?

The CleanLife Partner API is a RESTful HTTP API that enables authorized third-party companies — referred to as **partners** — to integrate directly with the CleanLife home-services platform. Through this API, partners can:

* Browse the live service catalog and pricing
* Query available appointment timeslots in real time
* Create and cancel bookings on behalf of their customers
* Confirm payments when the partner is responsible for billing

This API is **not** the internal CleanLife admin API and is not intended for end users. It is designed for business-to-business (B2B) server-side integrations by companies that wish to embed CleanLife services into their own platforms, applications, or workflows.

***

## Who Should Use This API?

| Audience                           | Description                                                                                                 |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Travel & Hospitality Platforms     | Hotels, Airbnb managers, or concierge services that offer cleaning as an add-on                             |
| Property Management Companies      | Companies managing residential or commercial properties that need automated recurring or on-demand bookings |
| E-commerce / Marketplace Platforms | Platforms bundling home services with their primary offering                                                |
| Enterprise Operations Teams        | Corporates managing employee or facility cleaning at scale                                                  |
| Third-Party Booking Apps           | Consumer-facing apps that delegate service fulfillment to CleanLife                                         |

***

## API Version

| Property            | Value                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------ |
| Current Version     | `v1`                                                                                       |
| Versioning Strategy | URI path versioning — breaking changes will introduce a new prefix (e.g. `/v2`)            |
| Deprecation Notice  | When a version is deprecated, partners will receive at least **90 days** of advance notice |

***

## Environments

The Partner API is available in two environments. Use **Sandbox** during development and testing; switch to **Production** only after your integration is validated.

| Environment    | Base URL                            | Purpose                                          |
| -------------- | ----------------------------------- | ------------------------------------------------ |
| **Sandbox**    | `https://apiv3.thecleanlife.dev/v1` | Development, testing, and integration validation |
| **Production** | `https://api.cleanlife.sa/v1`       | Live bookings and real customer data             |

All partner endpoints are prefixed with `/partners`:

```
# Sandbox
https://apiv3.thecleanlife.dev/v1/partners/...

# Production
https://api.cleanlife.sa/v1/partners/...
```

<Info>
  All code examples in this documentation use the **Sandbox** base URL by default. Replace it with the Production URL when you go live.
</Info>

***

## Supported Content Types

All request and response bodies use **JSON**.

| Direction | Header         | Value              |
| --------- | -------------- | ------------------ |
| Requests  | `Content-Type` | `application/json` |
| Responses | `Content-Type` | `application/json` |

Requests with a body that do not include `Content-Type: application/json` will be rejected with `400 Bad Request`.

***

## Character Encoding

All strings are UTF-8 encoded. Responses are UTF-8 encoded JSON.

***

## Timezone

All datetime values in requests and responses use the **Asia/Riyadh** timezone (UTC+3), unless explicitly stated otherwise in field documentation.

When passing timestamps, always use ISO 8601 format with the explicit `+03:00` offset:

```
2026-06-15T09:00:00+03:00
```

Date-only fields (e.g. booking dates) use the `YYYY-MM-DD` format in the Riyadh local date.

***

## Date and Time Format

| Type          | Format                 | Example                     |
| ------------- | ---------------------- | --------------------------- |
| Date          | `YYYY-MM-DD`           | `2026-06-15`                |
| DateTime      | ISO 8601 with `+03:00` | `2026-06-15T09:00:00+03:00` |
| Timeslot time | `HH:MM` or `HH:MM:SS`  | `09:00` or `09:00:00`       |

***

## Versioning Strategy

The Partner API uses **URI path versioning**. The current version is `v1`, included in the base URL (e.g. `https://apiv3.thecleanlife.dev/v1`). If a future breaking version is introduced, it will be explicitly namespaced (e.g. `/v2/partners/...`).

Additive, non-breaking changes (new optional fields) may be introduced without a version bump. Partners should build their integrations to **tolerate unknown fields** in responses.