Skip to main content
Conventions for all Partner API requests.

​
Base URL & Versioning

EnvironmentBase URL
Sandboxhttps://apiv3.thecleanlife.dev/v1
Productionhttps://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

MethodUsage
GETRead resources (catalog, bookings, webhooks)
POSTCreate resources (bookings, webhook subscriptions, price calculation)
PATCHPartial updates (booking update, cancel, webhook subscription)
DELETERemove webhook subscriptions

​
Required Headers

HeaderRequiredDescription
x-api-keyYesPartner API key
Content-TypeYes (POST/PATCH)application/json
x-request-idNoClient 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:
ParameterTypeDefaultDescription
pageinteger1Page number (1-based)
limitinteger20Items per page (max 100)
sortBystring—Field to sort by (endpoint-specific)
sortOrderASC | DESC—Sort direction

​
Example

GET /partners/bookings?page=2&limit=50&sortOrder=DESC

​
Filtering

Booking list supports additional filters (see List Bookings):
  • status — booking status
  • fromDate / toDate — date range (YYYY-MM-DD)
  • externalReference — your order reference
Webhook deliveries support subscriptionId and status filters.

​
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). Large webhook event payloads are generated server-side; your endpoint should accept at least 64 KB.