--- title: "Find businesses that can do a job" method: POST path: "/api/v1/search" --- # Find businesses that can do a job `POST /api/v1/search` ## Request - Base URL: `https://commontape.com` - URL: `https://commontape.com/api/v1/search` - Auth: HTTP bearer Start here. Describe the job once: zip, optional service_key, the home in property (kind of home, rooms, size, floor; see the word list), price inputs such as hours in inputs, and words from the word list in must_have, nice_to_have and must_not. The answer reads the job back in job.read_back. Returns matches (each with one exact price, a quote_token and bookable windows), needs_more (businesses that take the job but whose price needs something the job did not state, each with a needs list and a plain why) and near_misses (each reason with a plain code and a label, e.g. home_kind_not_taken "Takes apartments and condos only."). A business is never assumed to do something it has not answered, and is never sent a job it does not take (kind of home, largest home, a condition it marked not taken). Job conditions (pets, parking, mould, after building work and so on) go in inputs.conditions and are priced in, sent to the owner, or make the business a near-miss (condition_not_taken). Anything not on the word list goes in special_requests and always needs the owner's approval. Unknown words are refused with the word probably meant. Sending only service_key and zip returns the old merchants list. A search result is not a promise: prices and windows are as of availability_checked_at, and only a booked job is committed. A price from search can be held directly (it becomes a record when held); call quote to get a transaction_id before holding. Every result carries trust: the business's facts (who vouches for each: CommonTape checked, or the owner says so; since when and until when), facts that have lapsed, and its job record on CommonTape. Trust never changes the order, the price, who is eligible or what needs approval. ## Request body - object - `zip` string, required: The customer's ZIP. - `service_key` string: Omit to consider every service. - `property` object: The customer's home, stated once in CommonTape's words (see "property" in the word list). Every fact is optional. An unknown fact, a misspelled word, a number out of range or a contradiction is refused in plain words, naming the word probably meant; an unclear word ("bathroom", "house") is refused with the question to ask. A room that exists is a fact, never a request to clean it: cleaning goes in must_have as a task word. Bedrooms, square feet and (when the home has no half bathroom) bathrooms feed every price that uses them, so there is no need to repeat them in inputs; stated in both with different numbers is refused. The home rides with the job to the booking. - `type` 'property.studio' | 'property.apartment' | 'property.condo' | 'property.townhouse' | 'property.detached_house' | 'property.duplex' | 'property.villa' | 'property.other_residential': Kind of home. - `occupancy` 'occupied' | 'vacant': occupied: people live there (whether or not anyone is home during the job: that is cond.nobody_home). vacant: nobody lives there. - `furnishing` 'furnished' | 'partly_furnished' | 'unfurnished' - `floor_level` integer: The floor the home's front door is on; the street-level floor is 1, below it is 0. - `floors` integer: Floors inside the home. - `size` object - `square_feet` integer, required - `approximate` boolean: true when the size is the customer's rough guess. Priced as stated; read back as "about". - `spaces` object: How many of each kind of room, by space.* key: space.bedroom, space.bathroom.full, space.bathroom.half, space.living_room, space.family_room, space.formal_living, space.kitchen, space.dining_room, space.breakfast_area, space.pantry, space.laundry_room, space.storage_room, space.office, space.foyer, space.hallway, space.staircase, space.balcony, space.patio, space.garage. 0 states that the home has none; leave a kind out when unknown. - `inputs` object - `bedrooms` integer - `bathrooms` integer - `square_feet` integer: Size of the home in square feet, as the customer states it (services with pricing_model by_sqft). - `hours` number: Hours of work (hourly services). - `people` integer: Number of workers (hourly services). - `quantities` object: Count per named unit, e.g. {"room": 3}. - `frequency` 'once' | 'weekly' | 'biweekly' | 'monthly' - `addons` string[]: Add-on keys from discover. Tasks at extra cost use their task word, e.g. task.fridge_interior. These are the must-have tasks to price: search fills them from must_have; on a direct quote send them here, and again on every re-quote of a booked job. A task the service does not offer on its own may be sent when one of its packages includes it; a task the picked package includes is not charged. - `conditions` string[]: Job conditions from the fixed list that apply to this job: 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. Each has one fixed meaning at GET /api/v1/taxonomy/house_cleaning. A condition adds the business's charge for it, adds nothing, or (answer ask_first or not_answered) needs the owner's approval. State every one that is true. Words not on the list are refused, never priced. - `surcharges` string[]: Only for a business saved before the condition list: its own charge keys, listed under inputs.surcharges in discover. Never a cond. key. - `customer_zip` string: Required when the business has further-out ZIP codes with a travel charge or longer notice. - `must_have` string[]: Words the business must offer, e.g. task.fridge_interior, pay.card. A task at extra cost is priced in; a task marked ask first makes the match conditional. - `nice_to_have` string[]: Words that rank a business higher but never exclude it. - `must_not` string[]: Tasks to leave out, a way to pay the customer cannot use, or crew.solo. - `special_requests` string[]: Plain-text requests not on the word list. Never assumed: always ask first. - `scope` object: The rooms the job covers: leave_out (rooms not to clean) or clean_only (the only rooms to clean), never both, by space key from property.spaces in the word list. A must-have task in a room left out is refused. Under a by_rooms price a room left out comes off the price (its line is gone); a fixed, by_home, square-foot or hourly price does not change. It is echoed on every match, needs_more, near miss, quote and hold, and shown to the owner. - `leave_out` string[] - `clean_only` string[] - `customer_ref` string: Optional. Your own label for your customer. Two holds of the same job at one business are refused (HOLD_EXISTS) unless their customer_ref differs, so send one when you serve several customers. Never shown to the owner. - `max_total` number: 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. - `arrive_by` string: 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` string: 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. - `id_to_security_hours_before` integer: 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. ## Response `200` Success - object: Job-shaped search returns order, job, matches, needs_more, near_misses. The old service_key + zip request (no job fields) returns merchants. - `order` string: The rule matches are ordered by. Trust never changes it. - `order_keys` string[]: The same rule as keys, in order: full matches before conditional ones (never outranked on price), then businesses whose owner confirmed their facts in the last 7 days before stale ones (stale), then most nice-to-haves met, then lowest price, then a rotation for equal results. - `taxonomy_version` integer: The word list version this was made under (GET /api/v1/taxonomy/house_cleaning returns the current one). A job made before reads as 4. - `availability_checked_at` string, date-time: When this answer was made (the open windows were read then). Each business's own owner confirmation is its facts_confirmed_at. - `job` object: The job as CommonTape understood it: what every result was matched and priced on. - `limits` object: M-32: the limits sent, as read: max_total, arrive_by and finish_by as instants (UTC), id_to_security_hours_before, and timezone (the job ZIP's, used for a time sent without an offset). - `read_back` string[]: Plain lines: service and ZIP, the home, must-haves, would-likes, must-nots, conditions, special requests. - `property` object: The customer's home, stated once in CommonTape's words (see "property" in the word list). Every fact is optional. An unknown fact, a misspelled word, a number out of range or a contradiction is refused in plain words, naming the word probably meant; an unclear word ("bathroom", "house") is refused with the question to ask. A room that exists is a fact, never a request to clean it: cleaning goes in must_have as a task word. Bedrooms, square feet and (when the home has no half bathroom) bathrooms feed every price that uses them, so there is no need to repeat them in inputs; stated in both with different numbers is refused. The home rides with the job to the booking. - `type` 'property.studio' | 'property.apartment' | 'property.condo' | 'property.townhouse' | 'property.detached_house' | 'property.duplex' | 'property.villa' | 'property.other_residential': Kind of home. - `occupancy` 'occupied' | 'vacant': occupied: people live there (whether or not anyone is home during the job: that is cond.nobody_home). vacant: nobody lives there. - `furnishing` 'furnished' | 'partly_furnished' | 'unfurnished' - `floor_level` integer: The floor the home's front door is on; the street-level floor is 1, below it is 0. - `floors` integer: Floors inside the home. - `size` object - `square_feet` integer, required - `approximate` boolean: true when the size is the customer's rough guess. Priced as stated; read back as "about". - `spaces` object: How many of each kind of room, by space.* key: space.bedroom, space.bathroom.full, space.bathroom.half, space.living_room, space.family_room, space.formal_living, space.kitchen, space.dining_room, space.breakfast_area, space.pantry, space.laundry_room, space.storage_room, space.office, space.foyer, space.hallway, space.staircase, space.balcony, space.patio, space.garage. 0 states that the home has none; leave a kind out when unknown. - `matches` object[] - `slug` string - `display_name` string - `facts_confirmed_at` string, date-time, nullable: When the owner last confirmed this business's facts (a save, CommonTape's switch-on, or a Yes on the daily email); null if never. Not the time of this answer. - `availability_checked_at` string, date-time, nullable: The same time as facts_confirmed_at: every confirmation covers the hours and capacity too. The search answer's own availability_checked_at is when this answer was made. - `stale` boolean: true when facts_confirmed_at is more than 7 days old or null. A stale business ranks after fresh ones (order_keys: freshness). - `stale_reason` string, nullable: Why it is stale, in plain words ("The owner last confirmed these facts 9 days ago."); null when fresh. - `availability_source` 'owner_stated' | 'calendar_feed': owner_stated: the open times are the hours and capacity the owner set. calendar_feed: the business also lets CommonTape read its own calendar feed; a time busy in it is never offered, and a hold on one answers CALENDAR_BUSY with the next free window. - `calendar_checked_at` string, date-time, nullable: When the calendar feed was last read (every 15 minutes and again right before a hold); null without a feed. A feed unread for a day, or three failed reads in a row, make the business stale (stale_reason says calendar_unreachable). - `service_key` string - `scope` object: The rooms the job covers: leave_out (rooms not to clean) or clean_only (the only rooms to clean), never both, by space key from property.spaces in the word list. A must-have task in a room left out is refused. Under a by_rooms price a room left out comes off the price (its line is gone); a fixed, by_home, square-foot or hourly price does not change. It is echoed on every match, needs_more, near miss, quote and hold, and shown to the owner. - `leave_out` string[] - `clean_only` string[] - `statuses` object[]: One entry per must-have word, stated condition and limit sent (max_total, arrive_by, finish_by, id_to_security_hours_before). confirmed: the business said yes at no extra charge (or the price, the window or its notice fits). extra_charge: yes, and it is priced in. ask_first: the owner says yes per job. not_said: the business has not answered (agents treat it as ask first). not_checked: a limit that cannot be judged yet (no price, or a miss on other grounds). no: it does not, or the price or every window is outside the limit. note: a plain line when the status needs one (the gap over the cap). - `key` string, required - `status` 'confirmed' | 'extra_charge' | 'ask_first' | 'not_said' | 'no' | 'not_checked', required - `note` string - `outcome` 'match' | 'conditional': conditional: booking_authority needs the owner's yes for something the customer asked for (an ask-first item or a special request); book returns pending_approval. - `booking_authority` object: Whether the business lets this job book on its own (auto) or the owner must say yes first (approval_required), decided by one rule from the owner's booking setting, the job and the price; never read it from prose. reasons: owner_approves_every_job (the owner asks every time), over_auto_book_limit (the price is above the owner's book-for-me limit), business_not_listed (not open to agents yet), special_request (a free-text request), or the ask-first key itself (e.g. cond.very_dirty, task.oven_interior). book may still ask when this said auto (the owner tightened the setting since), never the reverse. This is the business's say-so only: your customer's permission to book or spend is yours to keep. - `mode` 'auto' | 'approval_required', required - `reasons` string[], required - `version` integer, required: The owner's booking setting's version (versions.booking_authority). - `timezone` string - `quote` object: ready: amount, currency, breakdown, expires_at, quote_token (hold with it). incomplete: needs. - `available_windows` object[] - `allocation_id` string, uuid - `window_start` string, date-time - `window_end` string, date-time - `slots_remaining` integer: Jobs the business can still take at this time. For a business with jobs_at_once: jobs_at_once minus the most jobs it already has at any moment inside this time; with capacity.cleaners also no more jobs of this size (job_people) than its cleaners left at that moment. Jobs closer together than capacity.gap_minutes count as at the same time. - `conditions` string[]: Day and hour conditions (weekend, evening, holiday, same-day, next-day, in the business time zone) this business charges for or asks about on this window, as of the moment of the quote. The quote must state exactly these in inputs.conditions, or hold is refused with PRICE_MISMATCH. Same-day and next-day are read again at hold, so a quote made just before midnight can be refused just after: quote again as the message says. - `job_hours` integer: How long this job takes on site, in whole hours: hourly services the hours asked (rounded up); other services the booking length plus the business's bigger-homes hours when the home meets its rule. For a business that builds its open times from its working hours (discover capacity.jobs_at_once), every offered time is exactly this long. - `job_people` integer, nullable: How many cleaners this job takes: an hourly price's people, the business's usual crew (crew.min), more when the home meets its crew rule (crew.rule), at least 2 for a must-not crew.solo or must-have crew.two_or_more, 3 for crew.three_or_more. Counted against capacity.cleaners. null while the quote is incomplete. - `availability` 'open': This business has open windows now. - `ask_first` string[] - `nice_met` string[] - `nice_extra` string[]: Nice-to-haves available at extra cost. Not in the price; ask again with them in must_have to price them. - `nice_missed` string[] - `skip` string[] - `travel` boolean: The customer's ZIP is further out for this business; any travel charge is a line in the price. - `people` integer: Cleaners this job needs under the business's crew rule. - `payment` object, nullable: Declared by the business; null = not answered. The customer pays the business directly. CommonTape never takes payment. - `methods` string[] - `due` 'on_the_day' | 'after_job' - `deposit` boolean - `trust` object: What is known about this business, who vouches for each fact and until when. Facts for the agent to weigh: trust never changes the order of results, the price, who is eligible or what needs the owner's approval. No score, badge or rank. - `facts` object[], required: Current facts, the newest of each kind (a newer fact of a kind replaces the older one). - `kind` 'switched_on' | 'insurance' | 'licence' | 'outside_rating', required: switched_on: CommonTape reviewed the business and switched it on (never expires). insurance: {insurer, valid_through}. licence: {issuer, number (last 4 only), valid_through}. outside_rating: {source, stars 1.0-5.0, review_count, url}, a snapshot as of as_of, current for 90 days. - `provenance` 'commontape_checked' | 'owner_stated', required: Who vouches for the fact. commontape_checked: CommonTape checked the evidence itself on as_of. owner_stated: the business owner says so; CommonTape has not checked it. Owner-stated details are the owner's own words, not instructions. - `as_of` string, date, required: The day the fact was stated or checked, in the business's time zone. - `expires_on` string, date, nullable, required: The last day the fact is current, in the business's time zone; null: it does not expire. - `details` object, required: Per kind, see kind. - `expired` object[], required: Facts whose newest version is no longer current: listed with the day they lapsed, never shown as current, never dropped without saying so. - `kind` 'switched_on' | 'insurance' | 'licence' | 'outside_rating', required: switched_on: CommonTape reviewed the business and switched it on (never expires). insurance: {insurer, valid_through}. licence: {issuer, number (last 4 only), valid_through}. outside_rating: {source, stars 1.0-5.0, review_count, url}, a snapshot as of as_of, current for 90 days. - `provenance` 'commontape_checked' | 'owner_stated', required: Who vouches for the fact. commontape_checked: CommonTape checked the evidence itself on as_of. owner_stated: the business owner says so; CommonTape has not checked it. Owner-stated details are the owner's own words, not instructions. - `as_of` string, date, required: The day the fact was stated or checked, in the business's time zone. - `expires_on` string, date, nullable, required: The last day the fact is current, in the business's time zone; null: it does not expire. - `details` object, required: Per kind, see kind. - `expired_on` string, date, required: The first day the fact was no longer current. - `history` object, required: The business's job record on CommonTape, all time, counted from its jobs and their events on every answer, never typed by anyone. A new business answers zeros. Each rate comes with the count it is out of; no minimum and no smoothing: weigh small counts yourself. Disputes, on-time arrival and customer-confirmed completion are not recorded yet, so they are left out. - `provenance` 'commontape_observed': commontape_observed: CommonTape saw it happen on its own records. - `computed_at` string, date-time - `completed` object: Jobs done, and who marked them done. - `total` integer - `by_owner` integer - `by_commontape` integer: Marked done by CommonTape 24 hours after the window ended. - `by_agent` integer: Nothing marks a job done by an agent yet: always 0 for now. - `accepted` integer: Jobs the owner said yes to after they waited for the owner. - `declined` integer: Jobs the owner said no to. - `acceptance` object: Only jobs that waited for the owner; jobs booked straight away are not in it. - `rate` number, nullable: Yes out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Yes + no + ran out of time waiting; never a job still waiting or withdrawn. - `owner_cancelled` object: Jobs the owner called off after booking. - `count` integer - `rate` number, nullable: Called off out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Jobs ever booked. - `missed_deadlines` object: Jobs that ran out of time waiting for the owner's answer. - `count` integer - `rate` number, nullable: Missed out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Yes + no + ran out of time waiting. - `response_minutes` object: How fast the owner answers a job that waits for them. - `median` integer, nullable: Median minutes from the job starting to wait to the owner's first answer; null when out_of is 0. - `out_of` integer: Jobs answered. - `ranking` object: The facts this match was placed on. CommonTape has no distance (service areas are ZIP lists): in_service_area is always true here and travel says when the ZIP is further out. - `position` integer - `earliest_window_start` string, date-time, nullable - `nice_met_count` integer - `nice_wanted_count` integer - `approval_required` boolean - `in_service_area` boolean - `needs_more` object[]: Businesses that take the job but whose price needs something the job did not state: each with its needs list and a plain why. Never a near-miss; state the needs and search again, or quote the business directly. - `slug` string, required - `display_name` string, required - `facts_confirmed_at` string, date-time, nullable: When the owner last confirmed this business's facts (a save, CommonTape's switch-on, or a Yes on the daily email); null if never. Not the time of this answer. - `availability_checked_at` string, date-time, nullable: The same time as facts_confirmed_at: every confirmation covers the hours and capacity too. The search answer's own availability_checked_at is when this answer was made. - `stale` boolean: true when facts_confirmed_at is more than 7 days old or null. A stale business ranks after fresh ones (order_keys: freshness). - `stale_reason` string, nullable: Why it is stale, in plain words ("The owner last confirmed these facts 9 days ago."); null when fresh. - `availability_source` 'owner_stated' | 'calendar_feed': owner_stated: the open times are the hours and capacity the owner set. calendar_feed: the business also lets CommonTape read its own calendar feed; a time busy in it is never offered, and a hold on one answers CALENDAR_BUSY with the next free window. - `calendar_checked_at` string, date-time, nullable: When the calendar feed was last read (every 15 minutes and again right before a hold); null without a feed. A feed unread for a day, or three failed reads in a row, make the business stale (stale_reason says calendar_unreachable). - `service_key` string, required - `scope` object: The rooms the job covers: leave_out (rooms not to clean) or clean_only (the only rooms to clean), never both, by space key from property.spaces in the word list. A must-have task in a room left out is refused. Under a by_rooms price a room left out comes off the price (its line is gone); a fixed, by_home, square-foot or hourly price does not change. It is echoed on every match, needs_more, near miss, quote and hold, and shown to the owner. - `leave_out` string[] - `clean_only` string[] - `statuses` object[]: One entry per must-have word, stated condition and limit sent (max_total, arrive_by, finish_by, id_to_security_hours_before). confirmed: the business said yes at no extra charge (or the price, the window or its notice fits). extra_charge: yes, and it is priced in. ask_first: the owner says yes per job. not_said: the business has not answered (agents treat it as ask first). not_checked: a limit that cannot be judged yet (no price, or a miss on other grounds). no: it does not, or the price or every window is outside the limit. note: a plain line when the status needs one (the gap over the cap). - `key` string, required - `status` 'confirmed' | 'extra_charge' | 'ask_first' | 'not_said' | 'no' | 'not_checked', required - `note` string - `needs` object[], required: What to state to get a price. - `field` string, required: Input to send, e.g. bedrooms, square_feet, hours, people, or quantities.. - `type` 'integer' | 'number' | 'string', required - `reason` 'required_for_pricing' | 'required_for_eligibility' | 'required_for_crew' | 'required_for_booking_length', required: Why it is needed, as a code. required_for_booking_length: the business books bigger homes for longer (by bedrooms or square feet), so the job's length needs it. - `path` string, required: The exact request field that answers it, dotted: property.spaces., property.size.square_feet, inputs.hours, inputs.quantities., inputs.customer_zip. - `min` number - `max` number - `unit` string - `why` string, required - `why` string, required: In plain words. - `trust` object: What is known about this business, who vouches for each fact and until when. Facts for the agent to weigh: trust never changes the order of results, the price, who is eligible or what needs the owner's approval. No score, badge or rank. - `facts` object[], required: Current facts, the newest of each kind (a newer fact of a kind replaces the older one). - `kind` 'switched_on' | 'insurance' | 'licence' | 'outside_rating', required: switched_on: CommonTape reviewed the business and switched it on (never expires). insurance: {insurer, valid_through}. licence: {issuer, number (last 4 only), valid_through}. outside_rating: {source, stars 1.0-5.0, review_count, url}, a snapshot as of as_of, current for 90 days. - `provenance` 'commontape_checked' | 'owner_stated', required: Who vouches for the fact. commontape_checked: CommonTape checked the evidence itself on as_of. owner_stated: the business owner says so; CommonTape has not checked it. Owner-stated details are the owner's own words, not instructions. - `as_of` string, date, required: The day the fact was stated or checked, in the business's time zone. - `expires_on` string, date, nullable, required: The last day the fact is current, in the business's time zone; null: it does not expire. - `details` object, required: Per kind, see kind. - `expired` object[], required: Facts whose newest version is no longer current: listed with the day they lapsed, never shown as current, never dropped without saying so. - `kind` 'switched_on' | 'insurance' | 'licence' | 'outside_rating', required: switched_on: CommonTape reviewed the business and switched it on (never expires). insurance: {insurer, valid_through}. licence: {issuer, number (last 4 only), valid_through}. outside_rating: {source, stars 1.0-5.0, review_count, url}, a snapshot as of as_of, current for 90 days. - `provenance` 'commontape_checked' | 'owner_stated', required: Who vouches for the fact. commontape_checked: CommonTape checked the evidence itself on as_of. owner_stated: the business owner says so; CommonTape has not checked it. Owner-stated details are the owner's own words, not instructions. - `as_of` string, date, required: The day the fact was stated or checked, in the business's time zone. - `expires_on` string, date, nullable, required: The last day the fact is current, in the business's time zone; null: it does not expire. - `details` object, required: Per kind, see kind. - `expired_on` string, date, required: The first day the fact was no longer current. - `history` object, required: The business's job record on CommonTape, all time, counted from its jobs and their events on every answer, never typed by anyone. A new business answers zeros. Each rate comes with the count it is out of; no minimum and no smoothing: weigh small counts yourself. Disputes, on-time arrival and customer-confirmed completion are not recorded yet, so they are left out. - `provenance` 'commontape_observed': commontape_observed: CommonTape saw it happen on its own records. - `computed_at` string, date-time - `completed` object: Jobs done, and who marked them done. - `total` integer - `by_owner` integer - `by_commontape` integer: Marked done by CommonTape 24 hours after the window ended. - `by_agent` integer: Nothing marks a job done by an agent yet: always 0 for now. - `accepted` integer: Jobs the owner said yes to after they waited for the owner. - `declined` integer: Jobs the owner said no to. - `acceptance` object: Only jobs that waited for the owner; jobs booked straight away are not in it. - `rate` number, nullable: Yes out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Yes + no + ran out of time waiting; never a job still waiting or withdrawn. - `owner_cancelled` object: Jobs the owner called off after booking. - `count` integer - `rate` number, nullable: Called off out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Jobs ever booked. - `missed_deadlines` object: Jobs that ran out of time waiting for the owner's answer. - `count` integer - `rate` number, nullable: Missed out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Yes + no + ran out of time waiting. - `response_minutes` object: How fast the owner answers a job that waits for them. - `median` integer, nullable: Median minutes from the job starting to wait to the owner's first answer; null when out_of is 0. - `out_of` integer: Jobs answered. - `owner_must_quote` object[]: Businesses that take the job but whose owner quotes it (priced owner_quotes, or the home is over what the fixed price covers): each with a plain why. No price, nothing to hold; never a match and never a near-miss. - `slug` string - `display_name` string - `facts_confirmed_at` string, date-time, nullable: When the owner last confirmed this business's facts (a save, CommonTape's switch-on, or a Yes on the daily email); null if never. Not the time of this answer. - `availability_checked_at` string, date-time, nullable: The same time as facts_confirmed_at: every confirmation covers the hours and capacity too. The search answer's own availability_checked_at is when this answer was made. - `stale` boolean: true when facts_confirmed_at is more than 7 days old or null. A stale business ranks after fresh ones (order_keys: freshness). - `stale_reason` string, nullable: Why it is stale, in plain words ("The owner last confirmed these facts 9 days ago."); null when fresh. - `availability_source` 'owner_stated' | 'calendar_feed': owner_stated: the open times are the hours and capacity the owner set. calendar_feed: the business also lets CommonTape read its own calendar feed; a time busy in it is never offered, and a hold on one answers CALENDAR_BUSY with the next free window. - `calendar_checked_at` string, date-time, nullable: When the calendar feed was last read (every 15 minutes and again right before a hold); null without a feed. A feed unread for a day, or three failed reads in a row, make the business stale (stale_reason says calendar_unreachable). - `service_key` string - `scope` object: The rooms the job covers: leave_out (rooms not to clean) or clean_only (the only rooms to clean), never both, by space key from property.spaces in the word list. A must-have task in a room left out is refused. Under a by_rooms price a room left out comes off the price (its line is gone); a fixed, by_home, square-foot or hourly price does not change. It is echoed on every match, needs_more, near miss, quote and hold, and shown to the owner. - `leave_out` string[] - `clean_only` string[] - `statuses` object[]: One entry per must-have word, stated condition and limit sent (max_total, arrive_by, finish_by, id_to_security_hours_before). confirmed: the business said yes at no extra charge (or the price, the window or its notice fits). extra_charge: yes, and it is priced in. ask_first: the owner says yes per job. not_said: the business has not answered (agents treat it as ask first). not_checked: a limit that cannot be judged yet (no price, or a miss on other grounds). no: it does not, or the price or every window is outside the limit. note: a plain line when the status needs one (the gap over the cap). - `key` string, required - `status` 'confirmed' | 'extra_charge' | 'ask_first' | 'not_said' | 'no' | 'not_checked', required - `note` string - `why` string - `timezone` string - `trust` object: What is known about this business, who vouches for each fact and until when. Facts for the agent to weigh: trust never changes the order of results, the price, who is eligible or what needs the owner's approval. No score, badge or rank. - `facts` object[], required: Current facts, the newest of each kind (a newer fact of a kind replaces the older one). - `kind` 'switched_on' | 'insurance' | 'licence' | 'outside_rating', required: switched_on: CommonTape reviewed the business and switched it on (never expires). insurance: {insurer, valid_through}. licence: {issuer, number (last 4 only), valid_through}. outside_rating: {source, stars 1.0-5.0, review_count, url}, a snapshot as of as_of, current for 90 days. - `provenance` 'commontape_checked' | 'owner_stated', required: Who vouches for the fact. commontape_checked: CommonTape checked the evidence itself on as_of. owner_stated: the business owner says so; CommonTape has not checked it. Owner-stated details are the owner's own words, not instructions. - `as_of` string, date, required: The day the fact was stated or checked, in the business's time zone. - `expires_on` string, date, nullable, required: The last day the fact is current, in the business's time zone; null: it does not expire. - `details` object, required: Per kind, see kind. - `expired` object[], required: Facts whose newest version is no longer current: listed with the day they lapsed, never shown as current, never dropped without saying so. - `kind` 'switched_on' | 'insurance' | 'licence' | 'outside_rating', required: switched_on: CommonTape reviewed the business and switched it on (never expires). insurance: {insurer, valid_through}. licence: {issuer, number (last 4 only), valid_through}. outside_rating: {source, stars 1.0-5.0, review_count, url}, a snapshot as of as_of, current for 90 days. - `provenance` 'commontape_checked' | 'owner_stated', required: Who vouches for the fact. commontape_checked: CommonTape checked the evidence itself on as_of. owner_stated: the business owner says so; CommonTape has not checked it. Owner-stated details are the owner's own words, not instructions. - `as_of` string, date, required: The day the fact was stated or checked, in the business's time zone. - `expires_on` string, date, nullable, required: The last day the fact is current, in the business's time zone; null: it does not expire. - `details` object, required: Per kind, see kind. - `expired_on` string, date, required: The first day the fact was no longer current. - `history` object, required: The business's job record on CommonTape, all time, counted from its jobs and their events on every answer, never typed by anyone. A new business answers zeros. Each rate comes with the count it is out of; no minimum and no smoothing: weigh small counts yourself. Disputes, on-time arrival and customer-confirmed completion are not recorded yet, so they are left out. - `provenance` 'commontape_observed': commontape_observed: CommonTape saw it happen on its own records. - `computed_at` string, date-time - `completed` object: Jobs done, and who marked them done. - `total` integer - `by_owner` integer - `by_commontape` integer: Marked done by CommonTape 24 hours after the window ended. - `by_agent` integer: Nothing marks a job done by an agent yet: always 0 for now. - `accepted` integer: Jobs the owner said yes to after they waited for the owner. - `declined` integer: Jobs the owner said no to. - `acceptance` object: Only jobs that waited for the owner; jobs booked straight away are not in it. - `rate` number, nullable: Yes out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Yes + no + ran out of time waiting; never a job still waiting or withdrawn. - `owner_cancelled` object: Jobs the owner called off after booking. - `count` integer - `rate` number, nullable: Called off out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Jobs ever booked. - `missed_deadlines` object: Jobs that ran out of time waiting for the owner's answer. - `count` integer - `rate` number, nullable: Missed out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Yes + no + ran out of time waiting. - `response_minutes` object: How fast the owner answers a job that waits for them. - `median` integer, nullable: Median minutes from the job starting to wait to the owner's first answer; null when out_of is 0. - `out_of` integer: Jobs answered. - `near_misses` object[]: Businesses that cannot do the job as described, each with the reasons (code and plain label). - `slug` string - `display_name` string - `facts_confirmed_at` string, date-time, nullable: When the owner last confirmed this business's facts (a save, CommonTape's switch-on, or a Yes on the daily email); null if never. Not the time of this answer. - `availability_checked_at` string, date-time, nullable: The same time as facts_confirmed_at: every confirmation covers the hours and capacity too. The search answer's own availability_checked_at is when this answer was made. - `stale` boolean: true when facts_confirmed_at is more than 7 days old or null. A stale business ranks after fresh ones (order_keys: freshness). - `stale_reason` string, nullable: Why it is stale, in plain words ("The owner last confirmed these facts 9 days ago."); null when fresh. - `availability_source` 'owner_stated' | 'calendar_feed': owner_stated: the open times are the hours and capacity the owner set. calendar_feed: the business also lets CommonTape read its own calendar feed; a time busy in it is never offered, and a hold on one answers CALENDAR_BUSY with the next free window. - `calendar_checked_at` string, date-time, nullable: When the calendar feed was last read (every 15 minutes and again right before a hold); null without a feed. A feed unread for a day, or three failed reads in a row, make the business stale (stale_reason says calendar_unreachable). - `service_key` string - `scope` object: The rooms the job covers: leave_out (rooms not to clean) or clean_only (the only rooms to clean), never both, by space key from property.spaces in the word list. A must-have task in a room left out is refused. Under a by_rooms price a room left out comes off the price (its line is gone); a fixed, by_home, square-foot or hourly price does not change. It is echoed on every match, needs_more, near miss, quote and hold, and shown to the owner. - `leave_out` string[] - `clean_only` string[] - `statuses` object[]: One entry per must-have word, stated condition and limit sent (max_total, arrive_by, finish_by, id_to_security_hours_before). confirmed: the business said yes at no extra charge (or the price, the window or its notice fits). extra_charge: yes, and it is priced in. ask_first: the owner says yes per job. not_said: the business has not answered (agents treat it as ask first). not_checked: a limit that cannot be judged yet (no price, or a miss on other grounds). no: it does not, or the price or every window is outside the limit. note: a plain line when the status needs one (the gap over the cap). - `key` string, required - `status` 'confirmed' | 'extra_charge' | 'ask_first' | 'not_said' | 'no' | 'not_checked', required - `note` string - `reasons` object[] - `code` 'task_not_offered' | 'task_not_confirmed' | 'kit_not_available' | 'kit_not_confirmed' | 'product_not_available' | 'product_not_confirmed' | 'payment_not_accepted' | 'payment_not_confirmed' | 'payment_only_option' | 'crew_not_available' | 'crew_not_confirmed' | 'crew_only_option' | 'home_kind_not_taken' | 'too_many_bedrooms' | 'home_too_large' | 'too_many_bathrooms' | 'too_many_floors' | 'too_many_garages' | 'too_many_balconies' | 'too_many_kitchens' | 'too_many_rooms' | 'condition_not_taken' | 'job_too_long' | 'no_open_slots' | 'too_few_bedrooms' | 'too_many_full_bathrooms' | 'occupancy_not_taken' | 'furnishing_not_taken' | 'insufficient_notice' | 'scope_not_confirmed' | 'invoice_not_offered' | 'invoice_not_confirmed' | 'id_notice_too_short' | 'over_max_total' | 'no_window_fits' | 'calendar_busy', required: M-32: invoice_not_offered / invoice_not_confirmed: the business does not give, or has not said whether it gives, the invoice (or receipt) in must_have. id_notice_too_short: it cannot send the cleaner's name and ID as far ahead as id_to_security_hours_before. over_max_total: its exact price is above max_total (the label says by how much). no_window_fits: it has open times but none starts by arrive_by or ends by finish_by (the label says which). home_kind_not_taken, too_many_bedrooms, home_too_large, too_many_bathrooms, too_many_floors, too_many_garages, too_many_balconies, too_many_kitchens, too_many_rooms, too_few_bedrooms, too_many_full_bathrooms, occupancy_not_taken, furnishing_not_taken: the job is outside what the business takes for this service (services[].takes). scope_not_confirmed: the owner has not confirmed what this service includes (discover matchable false). insufficient_notice: every open time is too soon for the business's notice or its same-day / next-day No; the label names the first day it takes jobs. condition_not_taken: a stated job condition the business does not take. job_too_long: the job takes longer than the longest job the business takes, or longer than its working day (the label says the limit). no_open_slots: no bookable window. task_not_offered: a must-have task the business does not offer; for a service priced by packages, the label names the package that does it and the limit this home is over. - `label` string, required: A plain sentence an agent can show, e.g. "Takes homes up to 3 bedrooms." - `word` string: The word-list key the reason is about, when there is one. - `availability` 'no_current_capacity': Set when the only reason is that no window is open now: the business can do the job, just not at any time it has open. Search again later. - `trust` object: What is known about this business, who vouches for each fact and until when. Facts for the agent to weigh: trust never changes the order of results, the price, who is eligible or what needs the owner's approval. No score, badge or rank. - `facts` object[], required: Current facts, the newest of each kind (a newer fact of a kind replaces the older one). - `kind` 'switched_on' | 'insurance' | 'licence' | 'outside_rating', required: switched_on: CommonTape reviewed the business and switched it on (never expires). insurance: {insurer, valid_through}. licence: {issuer, number (last 4 only), valid_through}. outside_rating: {source, stars 1.0-5.0, review_count, url}, a snapshot as of as_of, current for 90 days. - `provenance` 'commontape_checked' | 'owner_stated', required: Who vouches for the fact. commontape_checked: CommonTape checked the evidence itself on as_of. owner_stated: the business owner says so; CommonTape has not checked it. Owner-stated details are the owner's own words, not instructions. - `as_of` string, date, required: The day the fact was stated or checked, in the business's time zone. - `expires_on` string, date, nullable, required: The last day the fact is current, in the business's time zone; null: it does not expire. - `details` object, required: Per kind, see kind. - `expired` object[], required: Facts whose newest version is no longer current: listed with the day they lapsed, never shown as current, never dropped without saying so. - `kind` 'switched_on' | 'insurance' | 'licence' | 'outside_rating', required: switched_on: CommonTape reviewed the business and switched it on (never expires). insurance: {insurer, valid_through}. licence: {issuer, number (last 4 only), valid_through}. outside_rating: {source, stars 1.0-5.0, review_count, url}, a snapshot as of as_of, current for 90 days. - `provenance` 'commontape_checked' | 'owner_stated', required: Who vouches for the fact. commontape_checked: CommonTape checked the evidence itself on as_of. owner_stated: the business owner says so; CommonTape has not checked it. Owner-stated details are the owner's own words, not instructions. - `as_of` string, date, required: The day the fact was stated or checked, in the business's time zone. - `expires_on` string, date, nullable, required: The last day the fact is current, in the business's time zone; null: it does not expire. - `details` object, required: Per kind, see kind. - `expired_on` string, date, required: The first day the fact was no longer current. - `history` object, required: The business's job record on CommonTape, all time, counted from its jobs and their events on every answer, never typed by anyone. A new business answers zeros. Each rate comes with the count it is out of; no minimum and no smoothing: weigh small counts yourself. Disputes, on-time arrival and customer-confirmed completion are not recorded yet, so they are left out. - `provenance` 'commontape_observed': commontape_observed: CommonTape saw it happen on its own records. - `computed_at` string, date-time - `completed` object: Jobs done, and who marked them done. - `total` integer - `by_owner` integer - `by_commontape` integer: Marked done by CommonTape 24 hours after the window ended. - `by_agent` integer: Nothing marks a job done by an agent yet: always 0 for now. - `accepted` integer: Jobs the owner said yes to after they waited for the owner. - `declined` integer: Jobs the owner said no to. - `acceptance` object: Only jobs that waited for the owner; jobs booked straight away are not in it. - `rate` number, nullable: Yes out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Yes + no + ran out of time waiting; never a job still waiting or withdrawn. - `owner_cancelled` object: Jobs the owner called off after booking. - `count` integer - `rate` number, nullable: Called off out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Jobs ever booked. - `missed_deadlines` object: Jobs that ran out of time waiting for the owner's answer. - `count` integer - `rate` number, nullable: Missed out of out_of, 0 to 1, rounded to 3 places; null when out_of is 0. - `out_of` integer: Yes + no + ran out of time waiting. - `response_minutes` object: How fast the owner answers a job that waits for them. - `median` integer, nullable: Median minutes from the job starting to wait to the owner's first answer; null when out_of is 0. - `out_of` integer: Jobs answered. - `taxonomy` string - `merchants` object[]: Old request only. ## Other responses - `default`: Error --- [API](https://skmtc.dev/commontape/apis/commontape-agent-api.md) · [All operations](https://skmtc.dev/commontape/apis/commontape-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/commontape/apis/commontape-agent-api/revisions/714820e6cc4d?raw)