Job status

The authoritative state of one of your jobs, and everything needed to act on it. Read it any time: it never changes the job. Before the owner says yes they see the customer's first name and initial, the ZIP and town, the job and the time. After a yes (booked or done) they also see the full name, phone, address and access instructions. A job that never reached the owner, or that ended without a yes, shows nothing of the customer. Agents never get the customer's details back.

post/api/v1/status

Request

  • Base URL: https://commontape.com
  • URL: https://commontape.com/api/v1/status
  • Auth: HTTP bearer

Request body

transaction_idstring uuid required

Response

Success

transaction_idstring uuid required
state'quote_incomplete' | 'quoted' | 'held' | 'pending_approval' | 'booked' | 'completed' | 'declined' | 'cancelled' | 'supplier_cancelled' | 'expired' required

One of ten states, each with one meaning. 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.

allowed_actionsstring[] required

The operations you may call on this job now. Anything else is refused (INVALID_STATE, ALREADY_BOOKED, ALREADY_CANCELLED).

next_actionsstring[] required

The suggested next steps, from a fixed list.

job_versioninteger nullable

The job's version. Every change to the job is a new version; old versions, their quotes and prices are kept, never written over.

jobobject

The current version of the job: service, priced inputs, must_have, nice_to_have, must_not, special_requests, scope, word list version. Send it again to quote the same job elsewhere.

hold_expires_atstring date-time nullable
alternatives_note'timed_out' | 'none_found'

Why alternatives is empty: none fit every must, or they could not be worked out within 4 seconds (the refusal is never delayed for them).

if_changed_note'timed_out' | 'none_found'

Why if_changed is empty: no business is one change away, or they could not be worked out within the 4 seconds (the ready alternatives are kept).

alternatives_worked_out_atstring date-time

When the alternatives on this answer were worked out (status keeps them up to 60 seconds).

service_keystring
inputsobject

The job as held: the priced inputs, plus scope (the rooms it covers) when one was stated.

quote_amountnumber nullable
quote_currencystring
capacity_allocation_idstring uuid nullable
taxonomy_versioninteger required

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.

Example response

{
  "taxonomy_version": 6
}

Changes

No recorded changes to this operation across all 1 revision of this API.