{
  "openapi": "3.1.0",
  "info": {
    "title": "NB Removalists booking API",
    "version": "1.0.0",
    "description": "Quote and book removals with NB Removalists (operated by NB REMOVALISTS PTY. LTD., ABN 17 698 624 529). Prices AUD incl. GST. Only submit bookings with the customer's explicit consent. Requests are saved and followed up by the NB team (status received). Deposits: when deposit_online is true, POST /api/checkout returns a Stripe checkout_url for the customer to pay (status becomes deposit_paid).",
    "contact": {
      "name": "NB REMOVALISTS PTY. LTD.",
      "email": "bookings@northernbeachesremovalists.com.au",
      "url": "https://harbourremovals.com.au"
    }
  },
  "servers": [
    {
      "url": "https://harbourremovals.com.au"
    }
  ],
  "paths": {
    "/api/quote": {
      "post": {
        "operationId": "getQuote",
        "summary": "Get an instant removal estimate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bedrooms"
                ],
                "properties": {
                  "bedrooms": {
                    "type": "string",
                    "enum": [
                      "1",
                      "2",
                      "3",
                      "4",
                      "5+"
                    ]
                  },
                  "moveDate": {
                    "type": "string",
                    "format": "date",
                    "description": "YYYY-MM-DD. Saturday = weekday rate, Sunday +10%, NSW public holiday +15%."
                  },
                  "approxMonth": {
                    "type": "string",
                    "description": "YYYY-MM if there is no exact date yet (Mon\u2013Sat rate used)."
                  },
                  "amount": {
                    "type": "string",
                    "enum": [
                      "Everything (full home)",
                      "Most of it",
                      "Just a few items"
                    ],
                    "default": "Everything (full home)"
                  },
                  "propertyType": {
                    "type": "string",
                    "enum": [
                      "House",
                      "Apartment / Unit",
                      "Townhouse",
                      "Office"
                    ]
                  },
                  "driveMinutes": {
                    "type": "number",
                    "description": "Optional drive time in minutes from 46 Palomar Parade, Freshwater to the furthest address. Call-out = max(30, rounded up to 15) minutes at the crew rate. Defaults to the 30-minute minimum."
                  }
                }
              },
              "example": {
                "bedrooms": "2",
                "moveDate": "2026-12-02"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Estimate",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "quote": {
                      "type": "object",
                      "properties": {
                        "currency": {
                          "type": "string"
                        },
                        "gst_included": {
                          "type": "boolean"
                        },
                        "day_type": {
                          "type": "string",
                          "enum": [
                            "weekday",
                            "saturday",
                            "sunday",
                            "publicHoliday"
                          ]
                        },
                        "pricing_basis": {
                          "type": "string",
                          "enum": [
                            "estimate",
                            "site_inspection"
                          ]
                        },
                        "crew": {
                          "type": "string"
                        },
                        "hourly_rate": {
                          "type": "number"
                        },
                        "estimated_hours": {
                          "type": "array",
                          "items": {
                            "type": "number"
                          }
                        },
                        "minimum_hours": {
                          "type": "number"
                        },
                        "bigger_truck_fee": {
                          "type": "number"
                        },
                        "estimate_excl_call_out": {
                          "type": "array",
                          "items": {
                            "type": "number"
                          },
                          "description": "[low, high] AUD incl. GST"
                        },
                        "call_out_minutes": {
                          "type": "number"
                        },
                        "call_out_fee": {
                          "type": "number"
                        },
                        "estimate_total": {
                          "type": "array",
                          "items": {
                            "type": "number"
                          },
                          "description": "[low, high] AUD incl. GST and call-out"
                        },
                        "guide_price_excl_call_out": {
                          "type": "number",
                          "description": "5+ bedrooms only"
                        },
                        "source": {
                          "type": "string"
                        },
                        "notes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          }
        }
      }
    },
    "/api/book": {
      "post": {
        "operationId": "createBooking",
        "summary": "Send a booking request. Saved immediately; returns booking_ref, price and status received.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "fromAddress",
                  "toAddress",
                  "bedrooms",
                  "name",
                  "phone",
                  "email"
                ],
                "description": "Booking request. All listed fields required. Give moveDate OR approxMonth.",
                "properties": {
                  "fromAddress": {
                    "type": "string"
                  },
                  "toAddress": {
                    "type": "string"
                  },
                  "moveDate": {
                    "type": "string",
                    "format": "date",
                    "description": "YYYY-MM-DD"
                  },
                  "approxMonth": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}$",
                    "description": "YYYY-MM when the date isn't set yet (date_status date_tbc)."
                  },
                  "bedrooms": {
                    "type": "string",
                    "enum": [
                      "1",
                      "2",
                      "3",
                      "4",
                      "5+"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string",
                    "description": "Australian mobile, e.g. 0412 345 678"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "amount": {
                    "type": "string",
                    "enum": [
                      "Everything (full home)",
                      "Most of it",
                      "Just a few items"
                    ]
                  },
                  "channel": {
                    "type": "string",
                    "description": "Set to 'api' when booking as an AI agent"
                  }
                }
              },
              "example": {
                "fromAddress": "12 Example St, Mosman NSW 2088",
                "toAddress": "5/20 Example Rd, Neutral Bay NSW 2089",
                "moveDate": "2026-12-05",
                "bedrooms": "2",
                "name": "Alex Example",
                "phone": "0412 345 678",
                "email": "alex@example.com",
                "channel": "api"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Saved. status received; date_status confirmed | date_tbc; pricing_basis estimate | site_inspection; deposit_online true|false; deposit {amount, currency, note} and checkout_url (channel api) when online payment is on"
          },
          "422": {
            "description": "Validation errors"
          },
          "502": {
            "description": "Could not save; ask the customer to call the phone number"
          },
          "503": {
            "description": "Storage not configured; call the phone number"
          }
        }
      },
      "patch": {
        "operationId": "updateBookingDetails",
        "summary": "Optional: add extra details to an existing booking. Alias: POST /api/book/details",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bookingRef"
                ],
                "description": "Optional extra details for an existing booking_ref (within 14 days).",
                "properties": {
                  "bookingRef": {
                    "type": "string",
                    "pattern": "^NBH-[A-Z0-9]{6,20}$"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "propertyType": {
                    "type": "string",
                    "enum": [
                      "House",
                      "Apartment / Unit",
                      "Townhouse",
                      "Office"
                    ]
                  },
                  "pickupAccess": {
                    "type": "string",
                    "enum": [
                      "",
                      "Ground level / easy",
                      "Lift",
                      "Stairs, no lift",
                      "Steep driveway",
                      "Long walk from truck"
                    ]
                  },
                  "dropoffAccess": {
                    "type": "string",
                    "enum": [
                      "",
                      "Ground level / easy",
                      "Lift",
                      "Stairs, no lift",
                      "Steep driveway",
                      "Long walk from truck"
                    ]
                  },
                  "parking": {
                    "type": "string"
                  },
                  "items": {
                    "type": "string",
                    "maxLength": 1000
                  },
                  "timePreference": {
                    "type": "string",
                    "enum": [
                      "Morning (first job)",
                      "Afternoon",
                      "No preference"
                    ]
                  },
                  "moveDate": {
                    "type": "string",
                    "format": "date",
                    "description": "Set the date if it was TBC"
                  },
                  "notes": {
                    "type": "string",
                    "maxLength": 1500
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved. status received"
          },
          "404": {
            "description": "Unknown or expired booking_ref"
          },
          "422": {
            "description": "Validation errors"
          }
        }
      }
    },
    "/api/checkout": {
      "post": {
        "operationId": "createDepositCheckout",
        "summary": "Get a Stripe Checkout link (checkout_url) for the booking's deposit, to hand to the customer. Amount is computed server-side. 501 when online payment is off.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bookingRef"
                ],
                "properties": {
                  "bookingRef": {
                    "type": "string",
                    "pattern": "^NBH-[A-Z0-9]{6,20}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{checkout_url, amount, currency} or {already_paid: true}"
          },
          "404": {
            "description": "Unknown booking_ref"
          },
          "409": {
            "description": "No deposit (site inspection)"
          },
          "501": {
            "description": "Online payment not available; ask the customer to call"
          }
        }
      }
    },
    "/api/book/deposit": {
      "post": {
        "operationId": "payDeposit",
        "summary": "Alias of POST /api/checkout. 501 when online payment is off.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bookingRef"
                ],
                "properties": {
                  "bookingRef": {
                    "type": "string",
                    "pattern": "^NBH-[A-Z0-9]{6,20}$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Same as /api/checkout"
          },
          "501": {
            "description": "not_available"
          }
        }
      }
    },
    "/api/book/details": {
      "post": {
        "operationId": "updateBookingDetailsPost",
        "summary": "Same as PATCH /api/book, for clients that can't send PATCH",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bookingRef"
                ],
                "description": "Optional extra details for an existing booking_ref (within 14 days).",
                "properties": {
                  "bookingRef": {
                    "type": "string",
                    "pattern": "^NBH-[A-Z0-9]{6,20}$"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "propertyType": {
                    "type": "string",
                    "enum": [
                      "House",
                      "Apartment / Unit",
                      "Townhouse",
                      "Office"
                    ]
                  },
                  "pickupAccess": {
                    "type": "string",
                    "enum": [
                      "",
                      "Ground level / easy",
                      "Lift",
                      "Stairs, no lift",
                      "Steep driveway",
                      "Long walk from truck"
                    ]
                  },
                  "dropoffAccess": {
                    "type": "string",
                    "enum": [
                      "",
                      "Ground level / easy",
                      "Lift",
                      "Stairs, no lift",
                      "Steep driveway",
                      "Long walk from truck"
                    ]
                  },
                  "parking": {
                    "type": "string"
                  },
                  "items": {
                    "type": "string",
                    "maxLength": 1000
                  },
                  "timePreference": {
                    "type": "string",
                    "enum": [
                      "Morning (first job)",
                      "Afternoon",
                      "No preference"
                    ]
                  },
                  "moveDate": {
                    "type": "string",
                    "format": "date",
                    "description": "Set the date if it was TBC"
                  },
                  "notes": {
                    "type": "string",
                    "maxLength": 1500
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved. status received"
          },
          "404": {
            "description": "Unknown or expired booking_ref"
          },
          "422": {
            "description": "Validation errors"
          }
        }
      }
    }
  }
}