Skip to main content

​
Overview

Returns a paginated list of all bookings created by your partner account. Results are sorted by creation date descending (newest first). You can filter by status, date range, or your own externalReference.

​
Endpoint

GET /partners/bookings

​
Authentication

Requires a valid API Key with the partner_bookings_read permission.

​
Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number. Default: 1. Min: 1.
limitintegerNoResults per page. Default: 20. Min: 1. Max: 100.
sortBystringNoField to sort by.
sortOrderstringNoASC or DESC. Default: DESC.
statusstringNoFilter by booking status (exact match). See Booking Statuses.
fromDateISO date stringNoFilter bookings on or after this service date. Format: YYYY-MM-DD.
toDateISO date stringNoFilter bookings on or before this service date. Format: YYYY-MM-DD.
externalReferencestringNoFilter by your exact externalReference value.
fromDate without toDate returns all bookings from that date forward. toDate without fromDate is ignored.

​
Example Requests

​
List all bookings (most recent first)

curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/bookings" \
  -H "x-api-key: YOUR_API_KEY"

​
Filter by status and date range

curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/bookings?status=in%20progress&fromDate=2026-06-01&toDate=2026-06-30&limit=50" \
  -H "x-api-key: YOUR_API_KEY"

​
Lookup by your own reference

curl -X GET "https://apiv3.thecleanlife.dev/v1/partners/bookings?externalReference=ORDER-20260615-001" \
  -H "x-api-key: YOUR_API_KEY"

​
Success Response

HTTP Status: 200 OK 
{
  "success": true,
  "data": [
    {
      "bookingId": "11111111-0000-0000-0000-000000000001",
      "externalReference": "ORDER-20260615-001",
      "appointmentId": "22222222-0000-0000-0000-000000000002",
      "status": "in progress",
      "paymentStatus": "NOT_REQUIRED",
      "trackingReference": "SA-0042",
      "date": "2026-06-20T00:00:00.000Z",
      "timeslot": {
        "startAt": "09:00",
        "endAt": "12:00",
        "endsAtNextDay": false
      },
      "appointment": {
        "id": "22222222-0000-0000-0000-000000000002",
        "name": "SA-0042",
        "status": "Scheduled",
        "scheduledStartDateTime": "2026-06-20T09:00:00+03:00",
        "scheduledEndDateTime": "2026-06-20T12:00:00+03:00"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

​
Error Responses

HTTP StatusCodeDescription
400VALIDATION_ERRORInvalid query parameter (e.g., limit > 100, invalid date format)
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENMissing partner_bookings_read permission

​
Notes

  • This endpoint only returns bookings created by your partner account. You cannot see bookings from other partners.
  • Bookings with status = failed may appear in results. These are bookings that could not be completed successfully and should be disregarded; create a new booking if needed.
  • The externalReference filter is an exact string match — it is not a substring search.
  • GET /partners/bookings/:bookingId/status — Get details for a single booking
  • POST /partners/bookings — Create a new booking