Getting Started

This guide walks you through everything you need to make your first successful API call.

Prerequisites Checklist

Before you can call any endpoint, you need the following:

A Partner Account provisioned by the CleanLife integration team
An API Key issued for your partner account
The correct permissions granted to your API Key for the operations you intend to perform

Contact the CleanLife partner integration team to obtain these.

Step 1 — Obtain Your API Key

API Keys are provisioned by the CleanLife platform and are tied directly to your partner account. You cannot self-register through the API. Once provisioned, you will receive:

An opaque API key string
A list of permissions granted to the key
An optional rate limit (requests per minute)

Security: Treat your API Key like a password. Never embed it in client-side code (browser JavaScript, mobile apps). Always call the Partner API from your backend servers.

Step 2 — Set Required Headers

Every request to the Partner API requires the following header:

Header	Required	Description
`x-api-key`	Yes	Your partner API key
`Content-Type`	Yes (for POST/PATCH)	Must be `application/json`
`x-request-id`	No	Your own idempotent request identifier; echoed back in `X-Request-Id` response header for tracing

Example

GET /v1/partners/pricing/tiers HTTP/1.1
Host: apiv3.thecleanlife.dev
x-api-key: pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Step 3 — Make Your First Call

The simplest call to verify your credentials is listing pricing tiers (no address required):

curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/pricing/tiers" \
  -H "x-api-key: pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A successful response looks like:

{
  "success": true,
  "data": [...]
}

To list bookable services by category, register a contact with address coordinates first via POST /partners/contacts, then call GET /partners/services?addressId=.... Each category in the response includes a services array — use services[].id as serviceId when booking and services[].price as the amount to charge your customer. See List Services for details. If your API key is invalid or missing, you will receive:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "...",
    "requestId": "a1b2c3d4-..."
  }
}

Step 4 — Understand Your Payment Responsibility

Every partner account has a paymentResponsibility configuration, which determines how payments for bookings are handled:

Value	Meaning
`CLEANOS`	CleanLife handles all payment collection from the end customer. The partner only creates bookings; CleanLife sends a payment link to the customer.
`PARTNER`	The partner is responsible for collecting payment from their customers. CleanLife accepts the booking and expects the partner to call Confirm Payment after charging their customer.

This affects which endpoints are available to you and how the booking workflow behaves. Know your paymentResponsibility before integrating.

Environments

Environment	Base URL	When to Use
Sandbox	`https://apiv3.thecleanlife.dev/v1`	Development and integration testing
Production	`https://api.cleanlife.sa/v1`	Live traffic after go-live approval

Start all integration work against the Sandbox environment. Your sandbox API key is separate from your production key — contact the CleanLife integration team to obtain both.

Example endpoint paths:

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

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

Quick Reference

Resource	Endpoint
Find or Create Contact	`POST /partners/contacts`
List Services	`GET /partners/services?addressId=...`
Get Available Timeslots	`GET /partners/timeslots/available`
Create Booking	`POST /partners/bookings`
Get Booking Status	`GET /partners/bookings/:bookingId/status`
List Cancellation Reasons	`GET /partners/bookings/cancellation-reasons`
Cancel Booking	`PATCH /partners/bookings/:bookingId/cancel`
Confirm Payment	`POST /partners/bookings/:bookingId/confirm-payment`

Overview

Integration

Data Models

Prerequisites Checklist

Step 1 — Obtain Your API Key

Step 2 — Set Required Headers

Example

Step 3 — Make Your First Call

Step 4 — Understand Your Payment Responsibility

Environments

Quick Reference

​Prerequisites Checklist

​Step 1 — Obtain Your API Key

​Step 2 — Set Required Headers

​Example

​Step 3 — Make Your First Call

​Step 4 — Understand Your Payment Responsibility

​Environments

​Quick Reference

Prerequisites Checklist

Step 1 — Obtain Your API Key

Step 2 — Set Required Headers

Example

Step 3 — Make Your First Call

Step 4 — Understand Your Payment Responsibility

Environments

Quick Reference