List Services

Overview

Returns a paginated list of service categories, each containing the services your partner account can offer at a specific customer address. Results are the intersection of:

Services enabled for your partner account (when restrictions are configured), and
Services available in the service zone that covers the address coordinates.

Call POST /partners/contacts first to obtain an addressId, then pass it here to discover valid serviceId values for booking and timeslot queries.

Endpoint

GET /partners/services

Authentication

Requires a valid API Key with the partner_services_read permission.

Query Parameters

Parameter	Type	Required	Description
`addressId`	UUID	Yes	Customer service address ID from `POST /partners/contacts` (`data.addressId`). Must have latitude and longitude.
`page`	integer	No	Page number (categories). Default: `1`.
`limit`	integer	No	Categories per page. Default: `20`. Max: `100`.

Example Request

curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/services?addressId=bbbbbbbb-0000-0000-0000-000000000002&page=1&limit=50" \
  -H "x-api-key: YOUR_API_KEY"

Success Response

HTTP Status: 200 OK

{
  "success": true,
  "data": [
    {
      "id": "cccccccc-0000-0000-0000-000000000003",
      "code": "REGULAR_CLEANING",
      "nameEn": "Regular Cleaning",
      "nameAr": "تنظيف عادي",
      "descriptionEn": "Standard home cleaning service",
      "descriptionAr": "خدمة تنظيف منزلية",
      "isActive": true,
      "services": [
        {
          "id": "dddddddd-0000-0000-0000-000000000004",
          "name": "2 Hours Cleaning",
          "price": 150
        },
        {
          "id": "eeeeeeee-0000-0000-0000-000000000005",
          "name": "3 Hours Cleaning",
          "price": 200
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

Response fields

Category object

Field	Type	Description
`id`	UUID	Category ID (for display/grouping only — do not send as `categoryId` when booking)
`code`	string \| null	Category code
`nameEn`	string	English name
`nameAr`	string	Arabic name
`descriptionEn`	string	English description
`descriptionAr`	string	Arabic description
`isActive`	boolean	Whether the category is active
`services`	array	Services in this category available at the address

Service object (nested in services)

Field	Type	Description
`id`	UUID	Service ID — use as `serviceId` when creating a booking
`name`	string	Service name
`price`	number	Price in SAR for your partner account. When CleanLife configures a partner-specific price, that value is returned (`0` means deferred payment — no upfront charge). If no partner price is configured for a service, the platform default price applies. The same price is locked on the booking at creation time.

Categories are ordered by internal sort order, then English name. Services within each category are ordered by name. Pagination applies to categories (top-level data items), not individual services.

Error Responses

HTTP Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing or invalid `addressId`, or address has no coordinates
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`FORBIDDEN`	Missing `partner_services_read` permission
`404`	`RESOURCE_NOT_FOUND`	Address not found

Notes

Always call this endpoint after POST /partners/contacts so you have an addressId with coordinates.
Cache results per addressId with a short TTL (e.g., 15–60 minutes). Availability can change as zones are updated.
Use services[].id as serviceId when creating bookings. You do not need to send categoryId — it is resolved automatically from the service.
price is partner-specific. The value returned for each service reflects the price configured for your partner account. A value of 0 means deferred payment (no upfront charge). Display this price to your customers — it is the amount that will be charged when you create a booking for that service.
An empty data array is a valid response — the address may be outside all service zones or no enabled service is available there.

POST /partners/contacts — Register the customer and obtain addressId
GET /partners/timeslots/available — Get available timeslots for a service at the same address

Contacts

Bookings

Service Catalog

Overview

Endpoint

Authentication

Query Parameters

Example Request

Success Response

Response fields

Error Responses

Notes

​Overview

​Endpoint

​Authentication

​Query Parameters

​Example Request

​Success Response

​Response fields

​Error Responses

​Notes

​Related Endpoints

Overview

Endpoint

Authentication

Query Parameters

Example Request

Success Response

Response fields

Error Responses

Notes

Related Endpoints