CommonTape

Cancel your own held, waiting (pending_approval) or booked job and release the slot. Optional reason: customer_changed_plans, customer_booked_elsewhere, booked_in_error, customer_other. The answer carries cancellation (by, at, reason, fee null, policy, capacity_released): CommonTape takes no cancellation fee. Already cancelled answers ALREADY_CANCELLED (with recovery when the business called it off).

Commit a hold with the customer's details. Returns booked, or pending_approval (the owner must say yes: the quote's booking_authority was approval_required, or the owner's booking setting tightened since; the time stays reserved; poll status until decide_by, about once a minute: the owner has up to 2 hours, never later than an hour before the job (a job starting within about an hour keeps its hold's time); jobs waiting count toward your open holds; with no answer by then the job is expired: the job ends and the reserved time is released; you may cancel while waiting), declined (with the owner's reason, its canonical code, next_actions and next_available) or expired. Booking an already booked job answers ALREADY_BOOKED. A declined or expired answer carries alternatives and if_changed (businesses one change away: never bookable from the item; ask the customer, then search again without change.word). Every answer carries state (one of quote_incomplete, quoted, held, pending_approval, booked, completed, declined, cancelled, supplier_cancelled, expired), allowed_actions and next_actions; every error carries a code and next_actions. quote_incomplete: Not priced yet: the job needs more facts. needs says which. Nothing is held. Allowed: quote. quoted: An exact price for one exact job version, until expires_at. Nothing is held: the time is not reserved yet. Allowed: hold, quote. held: A time is reserved for this job until hold_expires_at. Book it, or cancel to let it go. Allowed: book, cancel. pending_approval: Asked to book; the owner must say yes by approval.deadline. The time stays reserved while waiting. No answer by then and the job expires and the time is released. Allowed: status, cancel. booked: The owner is committed to do this job at this price and time. Allowed: status, quote, modify, cancel. completed: The job was done. completion.source says who marked it: the owner (merchant) or CommonTape after the window ended (system). Allowed: status. declined: The owner said no. decline.reason says why; decline.next_available is the next open time when there is one. Allowed: status, quote. cancelled: Called off by the agent. The time was released. Allowed: status, quote. supplier_cancelled: Called off by the owner after it was booked. The job can be quoted again elsewhere from job. Allowed: status, quote. expired: Ran out of time: the quote passed expires_at, or the hold or the owner's answer passed its deadline. The time was released. Allowed: status, quote.

Reserve one window from a quote: the quoted job becomes held (same transaction_id). An expired or replaced quote answers QUOTE_EXPIRED: quote again. M-19: pick a window of the quote's job_hours; a window of another length, or one no longer in the business's hours, answers OUTSIDE_HOURS. M-19b: the hold counts the job's cleaners (job_people) against the business's cleaners in all and keeps its time between jobs; a window that no longer fits answers CAPACITY_FULL. Holds expire; book before hold_expires_at. Refused with PRICE_MISMATCH when the quote does not state exactly the window's conditions (weekend, evening, holiday, same-day, next-day): quote again as the message says. M-18: the answer says what it holds (quote_id, price, window, booking_authority); a hold locks the price. If the business changed since the quote the job is judged again: a lower price is held and price_changed says so; a higher one is refused PRICE_CHANGED (old and new amount, reasons, a fresh quote_token) unless accept_price_up_to covers it. HOLD_EXISTS: you already hold this job at this business (transaction_id). BUSINESS_UNAVAILABLE: it stopped taking jobs or no longer does this one. Recoverable refusals carry alternatives (other times, other businesses; never one that breaks a must). Dead ends also carry if_changed: up to 2 businesses that could do the job if the customer gave up ONE thing (change.word), with the price then; never holdable from the item (no token, no slot): ask the customer, then search again without that word. Holds you let run out count: five in 24 hours and the next answers RATE_LIMITED with retry_after_seconds. M-21: a time that is too soon (notice, or the business's same-day / next-day No) answers INSUFFICIENT_NOTICE with error.earliest (RFC 3339, business offset): pick a later window or quote again; a weekend, evening or holiday No answers OUTSIDE_HOURS.

Commit a change to a booked job: first quote it again with its transaction_id, then modify with that quote_token, optionally moving it to another window. The job stays booked; the old version and price are kept. The answer and every refusal carry change: kinds (capacity, commercial, eligibility, approval, non_commercial), rechecked, price from and to; a refused change leaves the booked job as it was. Refused with NEEDS_OWNER_APPROVAL when the new quote adds, drops or rewords something the owner must approve, or would not book on its own and costs more or moves an owner-approved job. A job the business called off answers SUPPLIER_CANCELLED with recovery. Refused with PRICE_MISMATCH when it is for a different ZIP, leaves out a task the booked job asked for (send every booked task again in inputs.addons), drops the home (leaves out a fact of the home the booked job stated: its kind, size or a room count; new values are allowed; refused with next_actions cancel, search), or does not state exactly the day and hour conditions of the window (a job that stays in its window keeps the same-day or next-day condition it was booked with). The owner's yes covered one version only. Check the new quote's price against your customer's limit before you modify: a change is priced against the business's current offering. Moving to a time that is too soon answers INSUFFICIENT_NOTICE with error.earliest; a job that keeps its time is never re-checked.

Quote one merchant's service. Every quote is a record: it returns transaction_id, quote_id, job_version and state quoted (or quote_incomplete). Pass transaction_id to quote the same job again (its next version; everything asked for before is carried forward); on a booked job that quote is the change modify commits. A job that ended is never revived: quoting it starts a new job. Search already returns prices; a search price is not a promise and becomes a record only when held. status ready = one exact amount, breakdown, expires_at, quote_token; status incomplete = a needs list of inputs still missing (never a range). Call discover first to see each service's inputs. State every job condition that is true in inputs.conditions. A job the business does not take (its kind of home, largest home, or a condition it marked not taken) is refused in plain words. For a service priced by packages, send must-have tasks in inputs.addons. A task the business does not offer on its own is quoted only in a package that includes it. A ready quote's package.includes lists the tasks it covers. Includes bookable windows (allocation_id), each with the day and hour conditions the quote must state to hold it.

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.

The fixed word list (version, groups, every key with its label and synonyms) agents use to describe a job and a home. Public, no key; the same answer as GET /api/v1/taxonomy/house_cleaning. Word list version 6.

Describe one merchant: services with pricing_model (packages: each package with its price, limits, kinds and the tasks it includes; the price is the cheapest package that fits the whole home and does every must-have task), typed inputs (incl. its answer for every job condition: no_charge, extra_charge with amount, ask_first, not_taken, not_answered), add-ons and passport (what each service covers, per task word), the business time zone (timezone), service area (area, town and state in area_details, further-out ZIPs in travel), crew, takes (the kinds of home and the largest home it takes; null = not answered; services[].takes are the limits that apply to each service, which may be looser or tighter than the business: judge a job by those; ask_first_above and unsure mean the owner says yes first, never a miss), when (only its plain day-and-hour Nos: min_days_ahead, weekends, evening_starts, holidays; null = not answered), services[].matchable (false = task list not confirmed: not searchable or quotable, reason scope_not_confirmed), brings, products, payment (declared; the customer pays the business directly) and hours in that time zone.

Get your own key, no human needed. Send agent_name (what your agent is called), owner_label (the plain name business owners will see next to a job, 1-40 characters) and contact_email. The key (ct_live_...) is in the answer ONCE: keep it and send it as Authorization: Bearer <key>. Starter limits: 30 requests a minute, 3 open holds, 5 bookings a day; the email sent to contact_email carries a link that raises them to 60 a minute, 10 holds, no daily cap, and your key page (usage, rotate, revoke). 3 keys a day per address. The demo key needs no registration.

The authoritative state of one of your jobs and everything needed to act on it: the job (current version), price, quote, window, approval (what needs the owner's yes and why: reasons, the deadline, what happens at it), commitment (who committed the booking: the owner's rule or the owner; your call is your assertion for your customer), decline (reason, code, next_actions, next_available), completion (who marked it done), cancellation (who, when, why, no fee), receipt (what was booked, from the record, with a plain text confirmation for your customer), recovery on supplier_cancelled (the job to search again with), versions, and allowed_actions / next_actions. Never the customer's details. A dead end reached in the last 24 hours (declined, expired, cancelled because the business stopped taking jobs, supplier_cancelled) carries alternatives and if_changed, kept up to 60 seconds (alternatives_worked_out_at). Every answer carries state (one of quote_incomplete, quoted, held, pending_approval, booked, completed, declined, cancelled, supplier_cancelled, expired), allowed_actions and next_actions; every error carries a code and next_actions. quote_incomplete: Not priced yet: the job needs more facts. needs says which. Nothing is held. Allowed: quote. quoted: An exact price for one exact job version, until expires_at. Nothing is held: the time is not reserved yet. Allowed: hold, quote. held: A time is reserved for this job until hold_expires_at. Book it, or cancel to let it go. Allowed: book, cancel. pending_approval: Asked to book; the owner must say yes by approval.deadline. The time stays reserved while waiting. No answer by then and the job expires and the time is released. Allowed: status, cancel. booked: The owner is committed to do this job at this price and time. Allowed: status, quote, modify, cancel. completed: The job was done. completion.source says who marked it: the owner (merchant) or CommonTape after the window ended (system). Allowed: status. declined: The owner said no. decline.reason says why; decline.next_available is the next open time when there is one. Allowed: status, quote. cancelled: Called off by the agent. The time was released. Allowed: status, quote. supplier_cancelled: Called off by the owner after it was booked. The job can be quoted again elsewhere from job. Allowed: status, quote. expired: Ran out of time: the quote passed expires_at, or the hold or the owner's answer passed its deadline. The time was released. Allowed: status, quote.