handlediq-com Booking Status API

openapi: 3.2.0
info:
  title: 'HandledIQ: find and book home service Booking Status API'
  version: 1.4.1
  description: 'HandledIQ runs home service shops (heating and cooling, plumbing, electrical, roofing, pest control, junk removal, demolition and more). For a person''s own AI assistant: find_help with what they need and their ZIP finds the shops near them that do it, each with its own book price, all in, its soonest real open time and its signed record (work finished, callbacks, arrivals kept, ratings). hold_time holds one shop''s time for 10 minutes and that shop texts the person a link; the visit is booked only when the person books it on the shop''s page, never on your word. booking_status says whether they did. Once booked, move_booking has the shop text the person a link to pick a new time, and cancel_booking cancels for free within 3 days of booking, before the visit. Every price is all in, paid after the work. request_service with a shop''s business_id opens HandledIQ''s quote window on it, where the person does the same themselves; get_quote gives one shop''s price and times by its business_id. The same calls speak MCP at https://app.handlediq.com/agents/mcp.'
servers:
- url: https://app.handlediq.com/agents
tags:
- name: Booking Status
paths:
  /api/booking_status:
    post:
      operationId: booking_status
      summary: Check the booking
      description: 'Says where a quote stands: priced, waiting on the person (with minutes left on the hold), booked (when, and with which tech), they said it was not them, or the hold ran out. Once booked, it also says whether the tech is on the way, arrived (and whether inside the time promised), finished, or the visit was cancelled. Use it after hold_time, or later, to tell the person how it went. Reads only; sends nothing.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                quote_id:
                  type: string
                  description: The quote_id price gave.
              required:
              - quote_id
              additionalProperties: false
      responses:
        '200':
          description: Answered.
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    ok:
                      const: true
                  required:
                  - ok
                - type: object
                  properties:
                    quote_id:
                      type: string
                    state:
                      type: string
                      enum:
                      - priced
                      - waits_for_owner
                      - waiting
                      - ran_out
                      - declined
                      - booked
                      - canceled
                      - closed
                    said:
                      type: string
                    held_until:
                      type: string
                      format: date-time
                    minutes_left:
                      type: integer
                    visit:
                      type: object
                      description: 'The booked visit as it stands now: its time, its tech, and what has happened since the yes.'
                      properties:
                        when:
                          type: string
                        starts_at:
                          type: string
                          format: date-time
                        ends_at:
                          type: string
                          format: date-time
                        tech:
                          type:
                          - string
                          - 'null'
                        now:
                          type: string
                          enum:
                          - scheduled
                          - on_the_way
                          - arrived
                          - finished
                          - canceled
                          description: Where the visit has got to, from the tech's own taps and the visit's close.
                        on_the_way_at:
                          type: string
                          format: date-time
                        arrived_at:
                          type: string
                          format: date-time
                        finished_at:
                          type: string
                          format: date-time
                        canceled_at:
                          type: string
                          format: date-time
                        promise:
                          type: object
                          description: 'The time promised now, and how the arrival measured against it: open (its time has not ended), kept (arrived inside it), early or late (by minutes), missed, canceled, or unrecorded.'
                          properties:
                            window_start:
                              type: string
                              format: date-time
                            window_end:
                              type: string
                              format: date-time
                            standing:
                              type: string
                              enum:
                              - open
                              - kept
                              - early
                              - late
                              - missed
                              - canceled
                              - unrecorded
                            minutes:
                              type: integer
                          required:
                          - window_start
                          - window_end
                          - standing
                      required:
                      - when
                      - starts_at
                      - ends_at
                    change:
                      type: object
                      description: 'A change the person''s assistant asked for once booked: a cancel (done at once, free under the shop''s terms), or a move (the shop texted the person a link, and done once they picked a new time).'
                      properties:
                        asked:
                          type: string
                          enum:
                          - cancel
                          - move
                        asked_at:
                          type: string
                          format: date-time
                        texted_at:
                          type: string
                          format: date-time
                        done:
                          type: boolean
                      required:
                      - asked
                      - asked_at
                      - done
                  required:
                  - quote_id
                  - state
                  - said
        '400':
          description: The arguments were not a JSON object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
        '404':
          description: No such quote or shop.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
        '409':
          description: 'Not now: the quote''s state or the time changed.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
        '422':
          description: An argument to fix; the error says which.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
        '429':
          description: Too many calls; the error says when to come back.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Failure'
      tags:
      - Booking Status
components:
  schemas:
    Failure:
      type: object
      properties:
        ok:
          const: false
        error:
          type: string
      required:
      - ok
      - error