CleanItAll API Documentation

Integrate CleanItAll with your systems using our RESTful API. This documentation covers authentication, available endpoints, webhooks, and best practices.

Base URL: https://app.cleanitall.io/api/v1

Quick Start

Get started with the CleanItAll API in minutes

  1. Create an API Key

    Log in to CleanItAll, go to Settings → API Keys, and create a new key with the required permissions.

  2. Make Your First Request

    Use your API key in the X-API-Key header:

    curl -X GET “https://app.cleanitall.io/api/v1/jobs” \ -H “X-API-Key: jt_live_your_api_key_here”
  3. Handle the Response

    All responses are JSON formatted. Check the status code and parse the response body.

Authentication

All API requests require authentication using an API key. Include your key in one of these ways:

X-API-Key Header (Recommended)

X-API-Key: jt_live_your_api_key_here

Authorization Bearer Header

Authorization: Bearer jt_live_your_api_key_here
API Key Security
Keep your API key secure. Never expose it in client-side code or public repositories. If you believe your key has been compromised, regenerate it immediately in the dashboard.

Rate Limiting

API requests are limited to 1000 requests per hour per API key. Rate limit information is included in response headers:

  • X-RateLimit-Limit – Maximum requests per hour
  • X-RateLimit-Remaining – Requests remaining in current window
  • X-RateLimit-Reset – Unix timestamp when the limit resets

API Endpoints

Jobs

GET /api/v1/jobs read

List all jobs with optional filtering

Query Parameters

  • status – Filter by status (pending, in_progress, completed, cancelled)
  • customer_id – Filter by customer ID
  • assigned_to – Filter by assigned team member ID
  • scheduled_date – Filter by date (YYYY-MM-DD)
  • limit – Results per page (default: 50, max: 100)
  • offset – Pagination offset

Example Request

curl “https://app.cleanitall.io/api/v1/jobs?status=pending&limit=10” \ -H “X-API-Key: jt_live_xxx”
GET /api/v1/jobs/:id read

Get a single job by ID

POST /api/v1/jobs write

Create a new job

Request Body

{ “customer_id”: 123, “title”: “Window Cleaning – Full House”, “description”: “Full exterior window clean including frames”, “price”: 45.00, “scheduled_date”: “2025-01-15”, “scheduled_time”: “09:00”, “duration_minutes”: 60, “assigned_to”: 456, “address”: “123 Main Street, London, SW1A 1AA”, “notes”: “Gate code: 1234” }
PATCH /api/v1/jobs/:id write

Update an existing job. Only include fields you want to change.

POST /api/v1/jobs/:id/complete write

Mark a job as completed

Request Body

{ “completed_date”: “2025-01-15”, “notes”: “Completed without issues” }
DELETE /api/v1/jobs/:id delete

Delete a job

Customers

GET /api/v1/customers read

List all customers

Query Parameters

  • search – Search by name, email, or phone
  • limit – Results per page (default: 50)
  • offset – Pagination offset
POST /api/v1/customers write

Create a new customer

Request Body

{ “name”: “John Smith”, “email”: “john@example.com”, “phone”: “07700900123”, “address”: “123 Main Street”, “city”: “London”, “postcode”: “SW1A 1AA”, “notes”: “Prefers morning appointments” }
PATCH /api/v1/customers/:id write

Update an existing customer

Invoices

GET /api/v1/invoices read

List all invoices

Query Parameters

  • status – Filter by status (draft, pending, paid, overdue, cancelled)
  • customer_id – Filter by customer
  • from_date – From date (YYYY-MM-DD)
  • to_date – To date (YYYY-MM-DD)
POST /api/v1/invoices write

Create a new invoice

Request Body

{ “customer_id”: 123, “due_date”: “2025-02-01”, “items”: [ { “description”: “Window Cleaning”, “quantity”: 1, “unit_price”: 45.00 }, { “description”: “Gutter Clearing”, “quantity”: 1, “unit_price”: 35.00 } ], “notes”: “Thank you for your business!” }
POST /api/v1/invoices/:id/send write

Send an invoice to the customer via email

POST /api/v1/invoices/:id/mark-paid write

Mark an invoice as paid

Request Body

{ “payment_method”: “bank_transfer”, “payment_date”: “2025-01-20”, “notes”: “Received via BACS” }

Payments

GET /api/v1/payments read

List all payments

Query Parameters

  • customer_id – Filter by customer
  • invoice_id – Filter by invoice
  • from_date – From date (YYYY-MM-DD)
  • to_date – To date (YYYY-MM-DD)
POST /api/v1/payments write

Record a payment

Request Body

{ “customer_id”: 123, “invoice_id”: 456, “amount”: 80.00, “payment_method”: “card”, “payment_date”: “2025-01-20”, “reference”: “TXN123456” }

Webhooks

Receive real-time notifications when events occur in your CleanItAll account. Webhooks are HTTP callbacks that send data to your specified URL when triggered by events.

Available Events

Job Events
  • job.created
  • job.updated
  • job.completed
  • job.cancelled
Invoice Events
  • invoice.created
  • invoice.sent
  • invoice.paid
  • invoice.overdue
Customer Events
  • customer.created
  • customer.updated
  • customer.deleted
Payment Events
  • payment.received

Webhook Payload

Headers

  • X-Webhook-Signature – HMAC-SHA256 signature for verification
  • X-Webhook-Event – Event type (e.g., job.created)
  • X-Webhook-Id – Unique webhook delivery ID

Example Payload

{ “id”: “evt_1234567890_abc123”, “type”: “job.completed”, “created_at”: “2025-01-15T10:30:00Z”, “data”: { “job”: { “id”: 123, “title”: “Window Cleaning”, “customer_id”: 456, “status”: “completed”, “completed_date”: “2025-01-15”, “price”: 45.00 } } }

Verifying Webhook Signatures

Always verify webhook signatures to ensure requests are from CleanItAll:

const crypto = require(‘crypto’); function verifyWebhookSignature(payload, signature, secret) { const expected = ‘sha256=’ + crypto .createHmac(‘sha256’, secret) .update(JSON.stringify(payload)) .digest(‘hex’); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); }

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

Code Description
200 Success – Request completed successfully
201 Created – Resource created successfully
400 Bad Request – Invalid parameters or missing required fields
401 Unauthorized – Invalid or missing API key
403 Forbidden – API key lacks required scope
404 Not Found – Resource does not exist
429 Too Many Requests – Rate limit exceeded
500 Internal Server Error – Something went wrong on our end

Error Response Format

{ “error”: “Validation failed”, “message”: “The customer_id field is required”, “field”: “customer_id” }

API Scopes

API keys can be configured with different scopes to limit access:

Scope Description
read Read-only access to resources (GET requests)
write Create and update resources (POST, PUT, PATCH requests)
delete Delete resources (DELETE requests)

Support

Need help with the API? We’re here to assist:

Pro Tip: Use the in-app API documentation at app.cleanitall.io/api-docs for interactive examples and the ability to copy code snippets with your actual API key pre-filled.