Request Standards

Conventions for all Partner API requests.

Base URL & Versioning

Environment	Base URL
Sandbox	`https://apiv3.thecleanlife.dev/v1`
Production	`https://api.cleanlife.sa/v1`

All partner routes follow this pattern:

{BASE_URL}/partners/{resource}

Examples:

# Sandbox
https://apiv3.thecleanlife.dev/v1/partners/services
https://apiv3.thecleanlife.dev/v1/partners/bookings

# Production
https://api.cleanlife.sa/v1/partners/services
https://api.cleanlife.sa/v1/partners/bookings

The API uses URI path versioning. The current version is v1 and is included in the base URL.

HTTP Methods

Method	Usage
`GET`	Read resources (catalog, bookings)
`POST`	Create resources (bookings, price calculation)
`PATCH`	Partial updates (booking cancel)

Required Headers

Header	Required	Description
`x-api-key`	Yes	Partner API key
`Content-Type`	Yes (POST/PATCH)	`application/json`
`x-request-id`	No	Client trace ID; echoed as `X-Request-Id`

JSON Conventions

Request bodies use camelCase field names.
Dates for booking creation use YYYY-MM-DD (e.g. 2026-06-20).
Timeslots use HH:mm 24-hour format (e.g. 09:00, 12:00).
All UUIDs must be valid UUID v4.

Pagination

List endpoints accept the following pagination query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (1-based)
`limit`	integer	`20`	Items per page (max `100`)
`sortBy`	string	—	Field to sort by (endpoint-specific)
`sortOrder`	`ASC` \| `DESC`	—	Sort direction

Example

GET /partners/services?addressId=bbbbbbbb-0000-0000-0000-000000000002&page=2&limit=50&sortOrder=DESC

Idempotency

— Idempotency-Key header support exists in the idempotency service layer but may not be enabled on all public booking endpoints. Confirm with the CleanLife integration team before relying on it in production.

When enabled, send:

Idempotency-Key: unique-key-per-logical-operation

Reusing the same key with the same payload replays the stored response. Reusing the key with a different payload returns a conflict error.

Date & Timezone

Business timezone: Asia/Riyadh (UTC+3).
API timestamps in responses use ISO 8601 with timezone offset where applicable.
Booking date is a calendar date in the service territory, not a UTC instant.

Request Size

Keep JSON payloads reasonable (under 1 MB).

Overview

Integration

Data Models

Base URL & Versioning

HTTP Methods

Required Headers

JSON Conventions

Example

Idempotency

Date & Timezone

Request Size

​Base URL & Versioning

​HTTP Methods

​Required Headers

​JSON Conventions

​Pagination

​Example

​Idempotency

​Date & Timezone

​Request Size

Base URL & Versioning

HTTP Methods

Required Headers

JSON Conventions

Pagination

Example

Idempotency

Date & Timezone

Request Size