Create Booking
Used by:POST /partners/bookings
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
contactId | UUID | Yes | Valid UUID v4 | ID of the customer contact (from POST /partners/contacts) |
addressId | string | Yes | Non-empty | ID of the service address |
serviceId | UUID | Yes | Valid UUID v4 | Service ID from your partner catalog. 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 |
packageId | UUID | No | Valid UUID v4 | Package ID |
customServices | array | No | Max items: — | Add-on custom services |
customServices[].id | UUID | Yes (if array) | Valid UUID v4 | Custom service ID |
customServices[].quantity | integer | No | Min: 1 | Quantity (default: 1) |
hours | integer | No | Min: 1; default: 1 | Duration in hours |
numberOfTeams | integer | No | Min: 2 | Number of teams (only if > 1 needed) |
workType | string | No | WorkType enum | Type of work to perform |
userId | UUID | No | Valid UUID v4 | CleanLife user ID (for coupon validation) |
couponIds | UUID[] | No | Max: 2 items; each valid UUID v4 | Coupon IDs to apply |
codes | string[] | No | Max: 2 items; each non-empty | Coupon or promo codes |
promoCode | string | No | — | Legacy promo code field |
contractCode | string | No | — | Contract pricing code |
discountCode | string | No | — | Discount code |
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 |
utmSource | string | No | — | Tracking source (default: PARTNER) |
Update Booking
Used by:PATCH /partners/bookings/:bookingId
All fields are optional.
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
date | string | No | ISO 8601 date | New service date |
timeslot | object | No | Valid object | New timeslot |
timeslot.startAt | string | No | Non-empty | New start time |
timeslot.endAt | string | No | Non-empty | New end time |
notes | string | No | — | Optional notes about the booking |
externalReference | string | No | — | New external reference (must be unique) |
Cancel Booking
Used by:PATCH /partners/bookings/:bookingId/cancel
All fields are optional.
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
reasonId | UUID | No | Valid UUID v4 | Predefined cancellation reason ID |
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 Bookings (query parameters)
Used by:GET /partners/bookings
| 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 | — | Sort field name |
sortOrder | string | No | ASC, DESC, asc, desc | Sort direction |
status | string | No | — | Booking status filter (exact match) |
fromDate | string | No | ISO 8601 date | Filter bookings on or after this date |
toDate | string | No | ISO 8601 date | Filter bookings on or before this date |
externalReference | string | No | — | Filter by exact externalReference value |
Pagination (query parameters)
Used by list endpoints such asGET /partners/bookings and GET /partners/webhooks/deliveries.
| 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 |
Create Webhook Subscription
Used by:POST /partners/webhooks/subscriptions
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
url | string (URL) | Yes | Valid URL (no TLD required), must pass domain validation | Webhook endpoint URL |
events | string[] | Yes | Array; each element must be a valid webhook event name | Events to subscribe to |
Update Webhook Subscription
Used by:PATCH /partners/webhooks/subscriptions/:id
All fields are optional.
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
url | string (URL) | No | Valid URL, domain validation | New webhook URL |
events | string[] | No | Each element must be a valid webhook event name | New event list (replaces existing) |
status | string | No | ACTIVE or INACTIVE | New subscription status |
List Webhook Deliveries (query parameters)
Used by:GET /partners/webhooks/deliveries
Supports pagination (page, limit, sortBy, sortOrder) plus:
| Parameter | Type | Required | Validation | Description |
|---|---|---|---|---|
subscriptionId | UUID | No | Valid UUID v4 | Filter by subscription ID |
status | string | No | Delivery status enum | Filter by delivery status |
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 |
Calculate Price
Used by:POST /partners/pricing/calculate-price
| Field | Type | Required | Validation | Description |
|---|---|---|---|---|
items | array | Yes | Min: 1 item; Max: 10 items | Array of price calculation items |
items[].hours | number | Yes | Min: 1; Max: 24 | Duration in hours |
items[].serviceId | UUID | Conditional | Valid UUID v4 | Required if packageId not provided |
items[].packageId | UUID | Conditional | Valid UUID v4 | Required if serviceId not provided |
items[].subServiceId | UUID | No | Valid UUID v4 | Sub-service add-on ID |
couponIds | UUID[] | No | Max: 2 items | Coupon IDs for discount preview |
codes | string[] | No | Max: 2 items | Coupon/promo codes for preview |
userId | UUID | No | Valid UUID v4 | User ID for coupon validation |
phone | string | No | — | Customer phone for coupon validation |