Book a held job

Commits the hold with the customer's details. State may be booked, or pending_approval if the owner must say yes (an ask-first task or condition, or any special request): poll status until decide_by. M-24b: the owner has up to 2 hours from book to answer, never later than an hour before the job (decide_by says when, and status.hold_expires_at then equals it; the hold reply's hold_expires_at is the agent's own, short, time to book). A job starting within about an hour keeps its hold's time. Poll status about once a minute. Jobs waiting count toward your open holds. While waiting the time stays reserved; at decide_by with no answer the job is expired: the job ends and the reserved time is released. You may cancel while waiting. Booking a job already booked answers ALREADY_BOOKED; a cancelled one ALREADY_CANCELLED; any other state INVALID_STATE. M-18: a hold that ran out answers expired with alternatives (other times here, other businesses; never one that breaks a must); a job the owner declined is refused INVALID_STATE (state declined) with alternatives; a business that stopped taking jobs since the hold answers BUSINESS_UNAVAILABLE, the job is called off and the time let go, with alternatives at other businesses.

post/api/v1/book

Request

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

Request body

transaction_idstring uuid required
idempotency_keystring required

Unique per write request (a UUID). Retrying with the same key returns the original result.

Response

Success

transaction_idstring uuid required
state'booked' | 'pending_approval' | 'declined' | '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[]

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

next_actionsstring[]

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.

decide_bystring date-time
reasonstring
next_availableobject nullable

The first same-business time in alternatives, kept for agents that read it.

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

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.