API for agents

Last updated: September 25, 2026

Serve is a home cleaning service in Greater Boston. Most cleaning companies cannot quote a home without a phone call or a visit. Serve prices one from a postal code and a room count in a single request, publishes the times it can actually clean, and takes the booking on an ordinary web page with no account to create. This page is the contract for all three.

No key, no account, no allow-list. Both endpoints below are public and open to every origin. There is nothing to sign up for and nothing to authenticate. If you are building an agent that shops for home cleaning, you can call them right now.

What an agent can do end to end

Price the home — POST /api/quote, one request, no key. You get a firm number, not a range.
Get real times — GET /api/slots returns the dates and times Serve can actually clean, up to three weeks out.
Hand over a prefilled booking — send your customer to servecleaning.com with the configuration you quoted on the query string. The page opens already filled in, and the price it shows is the price you were given.
Manage it afterwards — every booking is emailed a permanent private link where the visit can be rescheduled, cancelled, or paid for.

There is no booking endpoint, and that is deliberate rather than unfinished. The final confirmation collects the customer's own SMS consent and their own card details, and neither is something a third party should assert on their behalf. The steps an agent can do without a human — pricing and comparing — are the steps that are open.

Service area

Greater Boston and nearby towns: roughly 60 postal codes across Boston, Cambridge, Somerville, Brookline, Newton, Quincy, Medford, Malden, Watertown, Arlington and their neighbours. A postal code outside the area is refused, not priced — see out_of_area below. Do not cache the list; ask, because it grows.

1 · Price a home

POST https://servecleaning.com/api/quote

Send Content-Type: application/json. Typical response time is well under a second.

Request

Field	Type	Notes
`zip`	string	Required. 5-digit US postal code. A leading zero may be omitted — `2116` and `"02116"` are the same place.
`bedrooms`	number	0 for a studio. Homes of 5 or more are priced by hand — see `price_failed`.
`bathrooms`	number	Halves allowed: `1.5`.
`levels`	number	Floors in the home. Defaults to 1.
`service`	string	`first_clean` or `move_out`. A move-in / move-out clean covers an empty home, inside every cabinet, the fridge and the oven.
`condition`	string	`light`, `standard` or `heavy`. Defaults to `standard`. See the note below.
`frequency_selected`	string	`once`, `weekly`, `biweekly` or `monthly`. Defaults to `once`.
`addon_fridge`	boolean	Inside the fridge. First Clean only — a move clean already includes it.
`addon_oven`	boolean	Inside the oven. Same rule.

On condition. Serve's own booking form never asks a customer to grade their home. It asks two things they can actually answer — when it was last cleaned professionally, and whether there are pets — and derives the grade from those. Grading a home is a professional judgement, and asking an untrained person for it rewards whoever guesses lowest. If you want to match what the form would have said: cleaned recently and no pets is light; anything within a few months, or any home with pets, is standard; a long time or never is heavy.

Response

{
  "ok": true,
  "price": 195,
  "recurring": { "weekly": 121, "biweekly": 173, "monthly": 298 },
  "pricing_version": "2026-08-24",
  "quote_sig": "q1.1790362338.32802a14bd1111fd…",
  "quote_scope": "q1|02116|2|1|1|first_clean|standard|0|0|biweekly",
  "expires_at": 1790362338
}

price — the all-in total for this visit, in whole US dollars. Nothing is added later: no travel fee, no supplies charge, no per-room extra.
recurring — what each later visit would cost at each cadence, for this same home. Present whenever the home has a recurring track.
quote_sig and quote_scope — Serve's signature over this exact configuration, so the price can be honoured at booking. Pass them through unchanged if you have somewhere to put them; ignore them otherwise.
expires_at — Unix seconds. Signatures last two hours. The price itself does not change on that schedule; the signature does.

When it says no

Every outcome below is HTTP 200 with ok: false, except a malformed body (400) and a non-POST method (405). This endpoint is on the booking path and is built never to fail in a way that blocks a customer.

`error`	Meaning
`out_of_area`	Serve does not clean that postal code. The response echoes the `zip` it refused and carries no price and no signature. Do not fall back to a guess — there is no number here to use.
`no_zip`	No postal code was sent.
`price_failed`	This home is outside the flat-rate table — most often 5 or more bedrooms. It is quotable, by a person. Send the customer to the site.
`cannot_price`	Serve's pricing engine is unavailable. Rare, and worth retrying.
`bad_body`	Not JSON, empty, or over 10 KB. HTTP 400.
`method_not_allowed`	This endpoint takes `POST`. A `GET` will not price anything. HTTP 405.

Example

curl -s https://servecleaning.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{"zip":"02116","bedrooms":2,"bathrooms":1,
       "service":"first_clean","condition":"standard",
       "frequency_selected":"biweekly"}'

2 · Get real times

GET https://servecleaning.com/api/slots

No parameters, no key. Returns the times Serve can currently clean, everywhere in the service area.

{
  "ok": true,
  "generated": "2026-09-25T16:55:36.270Z",
  "count": 39,
  "slots": [
    { "date": "2026-09-26", "time": "9:00 AM",  "open": 1 },
    { "date": "2026-09-26", "time": "1:30 PM",  "open": 1 }
  ]
}

date is a calendar date with no timezone. time is local to Boston (US Eastern).
Times start at least 18 hours out and run up to 21 days ahead.
open is always 1 on a listed slot. A time that cannot be booked is not listed. It is a flag, not a capacity count.
generated is when the feed was built. It is rebuilt at most every five minutes, so polling faster than that returns the same payload — please do not.
An ok: false body means availability is temporarily unreadable. It is still HTTP 200, and it means "ask again", not "no times exist".

A slot listed here is not held for you. Availability is published, not reserved, and a time can be taken by someone else between your request and the booking.

3 · Hand over a prefilled booking

Send your customer to the booking form with the configuration you quoted on the query string. The form opens already filled in and shows the same price.

https://servecleaning.com/?zip=02116&bedrooms=2&bathrooms=1
    &service=first_clean&frequency=biweekly&addon_oven=true#quote

It accepts the same names and the same values as /api/quote: zip, bedrooms, bathrooms, levels, service, frequency, condition, addon_fridge and addon_oven. Booleans accept true or 1.

Do not put your customer's name, phone, email or street address on that link. A URL is written to logs by every network it crosses, kept in browser history, and pasted into chats. The shape of the home belongs on a link; the person living in it does not. Those fields are typed into the form, where they travel in the request body instead.

Your customer completes the form, chooses one of the times from step 2, gives their own SMS consent, and authorizes their own card through Stripe. Serve emails them a confirmation with a permanent private link to the booking.

4 · After the booking

That private link is the same one every time, it does not expire, and it needs no password — the link itself is the key. From it, a customer or an agent they have given it to can see each visit and its price, reschedule, cancel, authorize payment, and record how to get in, where to park and whether there are pets.

Treat it the way you would treat a password. Anyone holding it can act on that customer's bookings. Access codes for entry are the one thing it will never read back, to anyone, including the customer.

Fair use

There is no rate limit and no key, which is a choice that depends on people not abusing it. Two requests, please:

Do not poll /api/slots faster than once every five minutes. It is rebuilt no more often than that, so a faster loop costs Serve real capacity and returns you an identical payload.
Quote the homes your customer is actually asking about, rather than enumerating the price table.

If you are building something that needs more than this, write to us — the address is at the bottom of this page — rather than working around it.

Terms

Use of these endpoints, and any booking made through them, is governed by Serve's Terms of Service. Section 4 covers acting on a customer's behalf as an AI agent, and section 5 covers when a card is authorized and when it is charged. The Privacy Policy covers what Serve stores.