Working with an assistant

For AI agents

A guide for AI assistants acting for someone who wants a home or office clean in Toronto or the GTA.

The quickest way for a person to book

Send them to book online. They choose their service, see their price upfront and choose their time. They complete their booking and card details in BookingKoala. There’s no upfront payment.

If they want a quote first, use the quote API or MCP tool below with their permission. The team reviews the request; automatic quoting may be paused. Check private status for the price and a link to book, and let the person book on that link.

Book online

Start with the site’s own facts

Read our services and pricing, then use the person’s details when requesting their quote.

Regular Cleaning: Regular visits, weekly, bi-weekly or every 3 or 4 weeks, that keep your kitchen, bathrooms, floors and every reachable surface fresh, by vetted cleaners who bring all the supplies.
Deep Cleaning: A top-to-bottom reset for the baseboards, vents, door frames and corners everyday cleaning misses, and the right start when your home hasn’t had a professional clean in the past month.
Move In/Out Cleaning: A top-to-bottom clean of an empty home, before you move in or after you move out, from the kitchen and bathrooms to the baseboards, vents and fans.
Post-Renovation Cleaning: For the home you’ve just updated, from a new kitchen or bathroom to fresh floors, paint or a finished basement: we lift the renovation dust, room by room.
Office Cleaning: Offices of any size, from a one-room practice to a large workplace: desks, kitchens, bathrooms and floors cleaned thoroughly, so your team and your clients walk into a space that feels cared for.

For coverage, check our service areas and the service area FAQ. A postal code in the right format is a quote input, not confirmation of coverage.

See the terms and conditions for the full policies. For a question about the person’s clean, call (647) 424-0355 or email support@torontoshinecleaning.ca.

Request a cleaning quote

Send a POST with Content-Type: application/json to https://torontoshinecleaning.ca/api/agent-quote.php.

The team will review your request. Check private status for updates; automatic quoting may be paused. The quote link and price come back through private status only; neither the agent nor the client receives an automatic quote email. Give the person the link: the quote page in our booking system, BookingKoala, shows the price and lets them choose a time and add a card. Some requests need a person, such as office cleaning, interior windows or very large homes; those go to team review.

A quote is not a confirmed booking: the person picks a date and time and adds a card on the quote page. Preferred dates and times are passed on as notes.

The details to send

postal_code: the full Canadian postal code, such as M5V 2T6. The first three characters alone are accepted, but then the request goes to team review.
service: regular (Regular Cleaning), deep (Deep Cleaning), move_in_out (Move In/Out Cleaning), post_renovation (Post-Renovation Cleaning), office (Office Cleaning).
bedrooms, bathrooms and square_feet: the home’s actual size. Use 0 bedrooms for a studio; half bathrooms are accepted. For an office, send square_feet and omit bedrooms and bathrooms.
client.name, client.email and agent.reply_email.
consent.client_authorized: true: confirmation that the person asked you to send this request and share their details.

Optional frequency: one_time (One-time), weekly (Weekly), biweekly (Bi-weekly), every_4_weeks (Every 4 weeks). If you leave it out, the request is for a one-time clean.

Optional extras, using these IDs:

inside_oven: Inside oven
inside_fridge: Inside fridge
inside_cabinets: Inside cabinets
windows_and_tracks: Windows and tracks
interior_walls: Interior walls
hand_wiped_baseboards: Hand-wiped baseboards
dishes: Dishes
laundry_and_folding: Laundry and folding
extra_appliances: Extra appliances
extra_cupboards: Extra cupboards
finished_basement: Finished basement
pet_hair: Pet hair

You can also send preferred_dates (ISO dates or a description), preferred_times, address (street, unit and city), access_notes, parking_note, pets_note and notes (up to 1,000 characters). Time preferences use Toronto local time.

For a call, set client.callback_requested to true and include client.phone. Add client.preferred_call_times if helpful. The quote is processed either way. A phone number is also required if client.contact_preference is phone or text; the quote reply remains in private status.

The combined address, notes, access_notes, parking_note, pets_note, preferred_dates and preferred_times frame must fit 2400 Unicode characters, including JSON escaping and fixed framing. Oversized frames are rejected, never truncated.

Existing BookingKoala customer matches require independently verified customer authorization through the team. Unconfirmed coverage, unresolved pricing and uncertain saves also go to operator review.

The agent’s name and operator are optional. agent.reply_email is a contact reference for operator review, not a verified identity or an automatic email recipient. An optional HTTPS agent.callback_url is stored with the request only. The server does not call it.

See the field contract and OpenAPI specification for types, limits and examples. Unknown fields are rejected.

Example request

curl 'https://torontoshinecleaning.ca/api/agent-quote.php' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 0123456789abcdef0123456789abcdef' \
  --data-binary '{
  "postal_code": "M5V 2T6",
  "service": "deep",
  "bedrooms": 1,
  "bathrooms": 1,
  "square_feet": 600,
  "frequency": "one_time",
  "extras": [
    "inside_fridge"
  ],
  "preferred_dates": [
    "Please ask me about dates"
  ],
  "preferred_times": [
    "Weekday daytime"
  ],
  "client": {
    "name": "Alex Example",
    "email": "alex@example.com",
    "contact_preference": "email",
    "callback_requested": false
  },
  "agent": {
    "name": "Personal assistant",
    "reply_email": "assistant@example.com"
  },
  "consent": {
    "client_authorized": true
  }
}'

The response and retries

A successful submission returns HTTP 202 with a request_id, status: "received", the processing note, a status_token and status_url, reply_channel: "private_status", booking_url and docs_url. Keep the request ID when discussing the quote with the team, and keep the status token private.

Reading the quote

The status URL contains only the request ID. Never add tokens to a URL: query tokens are rejected. Alternatively, POST JSON with only request_id and status_token to the same endpoint. quote_sent is a compatibility name meaning ready in private status, not an email-delivery claim.

GET the status_url with Authorization: Bearer <status_token> (or call the MCP tool get_quote_status with request_id and status_token). The status is received, processing, quote_sent, team_review (operator review needed) or declined (the message says why). With quote_sent you also get quote_url and price: currency, total_before_tax, optional sales_tax, total_first_cleaning and optional total_next_cleaning when a recurring total has been verified. Check no more than once a minute.

Use an Idempotency-Key of 1–128 letters, digits, dots, underscores, colons or hyphens; random recommended (UUIDs accepted). Save the first receipt: status_token is returned only once. Within 48 hours replay with the same key, semantically identical quote data and Idempotency-Token containing that token. Without the capability, a submission is new. A changed body conflicts with 409; a lost receipt or unknown/expired capability requires team reconciliation before resubmitting. MCP uses idempotency_key and idempotency_token.

The body limit is 16 KB. Accepted quote submissions are limited to three per IP per rolling hour and 20 across all agents, shared with MCP quote calls. Idempotent replays do not use another quote slot. A 429 includes Retry-After; wait before retrying. Field errors return 400, an oversized body 413, and a non-JSON content type 415. If you receive 503, contact the team before resubmitting.

Connect through MCP

The stateless Streamable HTTP endpoint is https://torontoshinecleaning.ca/api/mcp.php, using protocol version 2025-06-18. It accepts JSON-RPC 2.0 POST requests and responds with JSON. It does not open an SSE stream or require a session ID.

request_cleaning_quote accepts the same fields, authorization rule and quote limits as the REST endpoint. get_quote_status reads a request’s status and quote with the receipt’s request_id and status_token. get_business_info takes no arguments and returns the site’s services, service area, contact, booking link and policy facts.

A connection configuration may look like this; use your client’s HTTP connection format:

{
  "mcpServers": {
    "torontoshinecleaning": {
      "type": "http",
      "url": "https://torontoshinecleaning.ca/api/mcp.php"
    }
  }
}

Supported methods: initialize, notifications/initialized, tools/list, tools/call and ping. Send Content-Type: application/json and Accept: application/json, text/event-stream. After initialization, send MCP-Protocol-Version: 2025-06-18. An initialized notification returns 202 with no body. Other results and errors use JSON-RPC envelopes.

For MCP replay, send idempotency_key and idempotency_token alongside the original quote fields. The token is the first receipt’s status_token. The JSON-RPC ID may change. Submissions are server-to-server; browser CORS permits GET polling with Authorization only.

Permission, privacy and accurate answers

Ask the person before sending a quote request. Do not submit the human quote form or BookingKoala form on their behalf without their consent.
Use the site’s own facts and link to the relevant page. Never invent a price, available appointment time or booking confirmation.
Share only the details needed for the quote. Do not send card details, passwords or access codes.

Requests are kept privately. Eligible requests are normally sent to the staff inbox; accepted requests may instead be held for private review. A receipt is not proof of delivery or of a quote. See our privacy policy for how personal information is handled.

Machine-readable references: llms.txt, OpenAPI and booking fields.