> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecleanlife.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Prerequisites, API key setup, and making your first API call.

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)

<Info>
  **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.
</Info>

***

## 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

```http theme={null}
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):

```bash theme={null}
curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/pricing/tiers" \
  -H "x-api-key: pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

A successful response looks like:

```json theme={null}
{
  "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](endpoints/catalog/list-services) for details.

If your API key is invalid or missing, you will receive:

```json theme={null}
{
  "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 |

<Note>
  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.
</Note>

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` |