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:
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.
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/services 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 available services:
curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/services" \
-H "x-api-key: pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
{
"success": true,
"data": [...],
"meta": {
"page": 1,
"limit": 20,
"total": 45,
"totalPages": 3
}
}
{
"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. |
paymentResponsibility before integrating.
Step 5 — Register Webhook Domains (Optional but Recommended)
If you plan to receive webhook notifications, you must:
- Have at least one allowed webhook domain registered with your partner account (done by the CleanLife team)
- Create a webhook subscription via
POST /partners/webhooks/subscriptions
See the Webhooks guide for complete instructions.
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.
# 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 |
| Get Contact by ID | GET /partners/contacts/:contactId |
| List Services | GET /partners/services |
| Get Service Details | GET /partners/services/:serviceId |
| Get Available Timeslots | GET /partners/timeslots/available |
| Get Pricing Tiers | GET /partners/pricing/tiers |
| Calculate Price | POST /partners/pricing/calculate-price |
| Create Booking | POST /partners/bookings |
| List Bookings | GET /partners/bookings |
| Get Booking Status | GET /partners/bookings/:bookingId/status |
| Update Booking | PATCH /partners/bookings/:bookingId |
| Cancel Booking | PATCH /partners/bookings/:bookingId/cancel |
| Confirm Payment | POST /partners/bookings/:bookingId/confirm-payment |
| Create Webhook Subscription | POST /partners/webhooks/subscriptions |
| List Webhook Subscriptions | GET /partners/webhooks/subscriptions |
| Update Webhook Subscription | PATCH /partners/webhooks/subscriptions/:id |
| Delete Webhook Subscription | DELETE /partners/webhooks/subscriptions/:id |
| Rotate Webhook Secret | POST /partners/webhooks/subscriptions/:id/rotate-secret |
| List Webhook Deliveries | GET /partners/webhooks/deliveries |
| Retry Webhook Delivery | POST /partners/webhooks/deliveries/:id/retry |
