CommonTape

Reviewed 1d ago.

• tools: 10 tools scanned
• metadata: scanned

No findings.

Tools (10)

• 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) owne

• discover

  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 searcha

• quote

  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

• hold

  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 ac

• book

  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, book

• modify

  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

• cancel

  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).

• status

  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

• taxonomy

  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.

• register

  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>. Trial 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.