search
Start here. Every result carries trust (facts with who vouches for each and until when, lapsed facts, the job record); trust never changes the order, the price, who is eligible or what needs approval. A search result is not a promise: prices and windows are as of availability_checked_at, and only a booked job is committed. Every business line carries facts_confirmed_at (when its owner last confirmed its facts: a save, CommonTape's switch-on or a Yes on the daily email; null if never), stale (true when that is more than 7 days ago or never) and stale_reason in plain words; a stale business ranks after fresh ones (order_keys: outcome, freshness, nice_met, price, rotation). Describe the cleaning job once and get the businesses that can do it: matches (each with one exact price or a needs list, a quote_token and bookable windows, so you can go straight to hold) needs_more (businesses that take the job but whose price needs something the job did not state: a needs list and a plain why) owner_must_quote (businesses that take the job but whose owner quotes it: a plain why, no price, nothing to hold) and near_misses with the reasons they missed (each a plain code and a label). Each match carries booking_authority: auto (books on its own) or approval_required with its reasons (owner_approves_every_job, over_auto_book_limit, business_not_listed, special_request, or the ask-first key); outcome conditional = approval is needed for something the customer asked for, and book returns pending_approval. book may still ask when it said auto (the owner tightened the setting), never the reverse. It is the business's say-so only: your customer's permission to book or spend is yours to keep. Never assume a business does something not in its answer. Anything not on the word list goes in special_requests as plain text. Job conditions go in inputs.conditions (cond.same_day cond.next_day cond.weekend cond.evening cond.holiday cond.pets cond.no_free_parking cond.stairs_no_lift cond.very_dirty cond.nobody_home cond.mould cond.infestation cond.post_construction cond.gated_entry cond.lockbox_entry): each adds the business's charge, adds nothing, needs the owner's approval, or is not taken (the business is then a near-miss, condition_not_taken). A business is never sent a home it does not take (kind, bedrooms, size, bathrooms, floors). Words: task.floors task.dusting task.bathrooms task.kitchen_surfaces task.trash task.mirrors task.appliance_exteriors task.microwave_interior task.make_beds task.change_linen task.fridge_interior task.oven_interior task.cabinets_interior task.cabinet_fronts task.closets_interior task.baseboards task.doors_frames task.walls_spot task.light_fixtures task.vents task.windows_interior task.window_tracks task.blinds task.tile_grout task.upholstery task.pet_hair task.dishes task.laundry task.organizing task.balcony task.garage task.carpet_shampoo task.post_construction_dust brings.supplies brings.vacuum brings.mop brings.steam_cleaner brings.carpet_machine brings.ladder brings.high_reach brings.industrial_vacuum product.eco_friendly product.fragrance_free product.pet_safe product.uses_customer_products product.bleach_free product.hypoallergenic crew.solo crew.two_or_more crew.three_or_more pay.cash pay.card pay.bank_transfer pay.app pay.check invoice.receipt invoice.person invoice.company. Word list version 6. Each business line says availability_source (owner_stated, or calendar_feed when the business lets CommonTape read its own calendar: busy times are never offered) and calendar_checked_at.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | The customer's 5-digit US ZIP | |
| scope | No | The rooms the job covers: leave_out (rooms not to clean) or clean_only (the only rooms to clean), never both, by space.* key. Under a by_rooms price a room left out comes off the price; other prices do not change. Echoed on every answer and shown to the owner. | |
| inputs | No | The job's price inputs: hours, people, frequency, conditions, and bedrooms, bathrooms, square_feet when not stated in property. Each service uses only what its price needs. | |
| must_not | No | Tasks to leave out, a way to pay the customer cannot use, or crew.solo. | |
| property | No | The home, stated once with the words at /api/v1/taxonomy/house_cleaning (property). Unknown or unclear words are refused with the word meant or the question to ask. Bedrooms, bathrooms (when there is no half bathroom) and square feet feed each price that uses them; no need to repeat them in inputs. A by_rooms price and a fixed price's limits read property.spaces only (state every kind the price counts, 0 included; a living area is living + family + formal living rooms). | |
| arrive_by | No | Optional. The latest start: a date and time like 2026-10-09T10:00 (wall clock in the job ZIP's time zone, the business's zone) or with an offset (2026-10-09T14:00Z). Only windows that start by then are offered; none left is a near miss no_window_fits. Refused: a time that does not exist (clocks going forward), the past, more than 60 days ahead. | |
| finish_by | No | Optional. The latest finish, written like arrive_by: a window is offered only if it starts early enough to end by then (window start plus job_hours, else the window's end). After arrive_by when both are sent. | |
| max_total | No | Optional. The most the customer will pay in all, in dollars (travel and extra charges included). A priced business above it is a near miss over_max_total with the gap in dollars; a window whose own day or hour charge would take the price over it is left out; a business with no price yet (needs_more, owner_must_quote) is listed with max_total not_checked in statuses. | |
| must_have | No | Words the business must offer, e.g. task.fridge_interior, pay.card. Tasks at extra cost, or done only inside a package, are priced in. | |
| service_key | No | house_cleaning.standard | house_cleaning.deep | house_cleaning.move_in_out. Omit to consider all three. | |
| customer_ref | No | Optional. Your own label for your customer, so two customers with the same job are not the same job. Never shown to the owner. | |
| nice_to_have | No | Words that rank a business higher but never exclude it. | |
| special_requests | No | Up to 5 plain-text requests not on the word list. Always needs the owner's approval. | |
| id_to_security_hours_before | No | Optional, with cond.id_to_security in inputs.conditions. How many hours before the job the building wants each cleaner's name and photo ID (1 to 168). A business that can send them at least this far ahead meets it; one that cannot is a near miss id_notice_too_short; one that has not said is not_said in statuses. |