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

# Request Models

> All request body schemas with field-level types, validation, and descriptions.

Complete reference for all request bodies used in the Partner API.

***

## Create Booking

Used by: `POST /partners/bookings`

| Field               | Type   | Required | Validation    | Description                                                                                 |
| ------------------- | ------ | -------- | ------------- | ------------------------------------------------------------------------------------------- |
| `contactId`         | UUID   | **Yes**  | Valid UUID v4 | Customer contact ID (from `POST /partners/contacts`, field `id`)                            |
| `addressId`         | string | **Yes**  | Non-empty     | Service address ID (from `POST /partners/contacts`, field `addressId`)                      |
| `serviceId`         | UUID   | **Yes**  | Valid UUID v4 | Service ID from `GET /partners/services?addressId=...`. Category is resolved automatically. |
| `timeslot`          | object | **Yes**  | Valid object  | Appointment timeslot                                                                        |
| `timeslot.startAt`  | string | **Yes**  | Non-empty     | Start time (`HH:MM` or `HH:MM:SS`) in Riyadh local time                                     |
| `timeslot.endAt`    | string | **Yes**  | Non-empty     | End time (`HH:MM` or `HH:MM:SS`) in Riyadh local time                                       |
| `date`              | string | **Yes**  | ISO 8601 date | Service date (`YYYY-MM-DD`)                                                                 |
| `externalReference` | string | No       | Max 150 chars | Your unique reference ID for this booking                                                   |

***

## Create Contact

Used by: `POST /partners/contacts`

| Field          | Type   | Required | Validation                    | Description                                     |
| -------------- | ------ | -------- | ----------------------------- | ----------------------------------------------- |
| `phone`        | string | **Yes**  | Saudi phone number, no spaces | Customer phone (e.g. `+966500000000`)           |
| `name`         | string | **Yes**  | Non-empty                     | Customer full name                              |
| `latitude`     | string | No       | Valid latitude                | Address latitude; must be sent with `longitude` |
| `longitude`    | string | No       | Valid longitude               | Address longitude; must be sent with `latitude` |
| `cityName`     | string | No       | Non-empty when provided       | City name for the service address               |
| `districtName` | string | No       | Non-empty when provided       | District / neighborhood name                    |
| `streetName`   | string | No       | Non-empty when provided       | Street name for the service address             |

<Note>
  `utmSource` is not accepted in the request body. It is assigned automatically from your partner account name.
</Note>

***

## Cancel Booking

Used by: `PATCH /partners/bookings/:bookingId/cancel`

| Field      | Type   | Required | Validation    | Description                                                               |
| ---------- | ------ | -------- | ------------- | ------------------------------------------------------------------------- |
| `reasonId` | UUID   | **Yes**  | Valid UUID v4 | Cancellation reason ID from `GET /partners/bookings/cancellation-reasons` |
| `notes`    | string | No       | —             | Notes about the cancellation                                              |

***

## Confirm Payment

Used by: `POST /partners/bookings/:bookingId/confirm-payment`

All fields are optional.

| Field              | Type   | Required | Validation     | Description                                    |
| ------------------ | ------ | -------- | -------------- | ---------------------------------------------- |
| `paymentReference` | string | No       | Max: 255 chars | Your payment transaction ID for reconciliation |

***

## List Services (query parameters)

Used by: `GET /partners/services`

| Parameter   | Type    | Required | Validation                    | Description                                       |
| ----------- | ------- | -------- | ----------------------------- | ------------------------------------------------- |
| `addressId` | UUID    | **Yes**  | Valid UUID v4                 | Service address ID from `POST /partners/contacts` |
| `page`      | integer | No       | Min: 1; default: 1            | Page number (categories)                          |
| `limit`     | integer | No       | Min: 1; Max: 100; default: 20 | Categories per page                               |

***

## Pagination (query parameters)

Used by other list endpoints (e.g. booking history).

| Parameter   | Type    | Required | Validation                    | Description      |
| ----------- | ------- | -------- | ----------------------------- | ---------------- |
| `page`      | integer | No       | Min: 1; default: 1            | Page number      |
| `limit`     | integer | No       | Min: 1; Max: 100; default: 20 | Results per page |
| `sortBy`    | string  | No       | —                             | Field to sort by |
| `sortOrder` | string  | No       | `ASC`, `DESC`, `asc`, `desc`  | Sort direction   |

***

## Available Timeslots (query parameters)

Used by: `GET /partners/timeslots/available`

| Parameter   | Type   | Required | Validation    | Description                   |
| ----------- | ------ | -------- | ------------- | ----------------------------- |
| `addressId` | UUID   | **Yes**  | Valid UUID v4 | Customer's service address ID |
| `serviceId` | UUID   | **Yes**  | Valid UUID v4 | Service ID from the catalog   |
| `date`      | string | **Yes**  | ISO 8601 date | Desired service date          |