AI Home Services Booking

Read-only. Lists the trades supported and tells you whether a city in Canada or the United States is covered, and whether we already have a ranked provider shortlist there (pre_ranked) or will source providers when the request arrives (live_sourced). Call this before request_quotes if you are unsure the trade or city is supported. It does not create a request or contact anyone.

{
  "type": "object",
  "properties": {
    "trade": {
      "type": "string",
      "enum": [
        "plumber",
        "hvac",
        "electrician",
        "roofer",
        "appliance-repair",
        "locksmith",
        "garage-door",
        "pest-control",
        "handyman",
        "house-cleaning",
        "other"
      ],
      "description": "Home-service trade. Use 'other' with trade_detail for anything not listed."
    },
    "city": {
      "type": "string",
      "description": "City or municipality, for example 'Mississauga' or 'Austin'."
    },
    "region": {
      "type": "string",
      "description": "Province or state, for example 'ON' or 'TX'."
    },
    "country": {
      "type": "string",
      "enum": [
        "CA",
        "US"
      ],
      "description": "CA or US."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "supported_trades": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "supported_countries": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "coverage": {
      "type": [
        "object",
        "null"
      ]
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "supported_trades",
    "supported_countries",
    "note"
  ]
}

Use when a customer wants an agent to find and book a home-service contractor (plumber, HVAC, electrician, roofer, appliance repair, locksmith, garage door, pest control, handyman, house cleaning, or another trade) at an address in Canada or the United States. We contact multiple independent providers by email, SMS and phone, ask for price and availability, check the options with the customer, and coordinate the booking the customer approves. Human operators assist as needed. We aim to return viable options within one hour for urgent requests, but response time, quote count, price and availability are not guaranteed and may be slower where we have no pre-built provider shortlist. This call creates a service request; it does not confirm an appointment or authorize work. The customer chooses and pays the provider directly. Collect every required field from the customer first, including explicit consent to be contacted.

{
  "type": "object",
  "properties": {
    "trade": {
      "type": "string",
      "enum": [
        "plumber",
        "hvac",
        "electrician",
        "roofer",
        "appliance-repair",
        "locksmith",
        "garage-door",
        "pest-control",
        "handyman",
        "house-cleaning",
        "other"
      ],
      "description": "Home-service trade. Use 'other' with trade_detail for anything not listed."
    },
    "trade_detail": {
      "type": "string",
      "description": "Required when trade is 'other': the kind of contractor needed."
    },
    "country": {
      "type": "string",
      "enum": [
        "CA",
        "US"
      ]
    },
    "region": {
      "type": "string",
      "description": "Province or state code or name, for example 'ON' or 'Texas'."
    },
    "city": {
      "type": "string",
      "description": "City or municipality where service is needed."
    },
    "service_address": {
      "type": "string",
      "description": "Full street address where service is needed."
    },
    "postal_code": {
      "type": "string",
      "description": "Postal or ZIP code."
    },
    "problem": {
      "type": "string",
      "description": "What is needed or wrong, with relevant details."
    },
    "urgency": {
      "type": "string",
      "enum": [
        "emergency",
        "today",
        "next_day",
        "flexible"
      ]
    },
    "preferred_time": {
      "type": "string",
      "description": "Preferred appointment window in local time."
    },
    "contact_name": {
      "type": "string"
    },
    "phone": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "consent_to_contact": {
      "type": "boolean",
      "description": "Must be true. Allows us and prospective providers to contact the customer about this request."
    },
    "source_platform": {
      "type": "string",
      "description": "Calling agent or platform, if known."
    }
  },
  "required": [
    "trade",
    "country",
    "region",
    "city",
    "service_address",
    "problem",
    "urgency",
    "contact_name",
    "consent_to_contact"
  ],
  "additionalProperties": false,
  "anyOf": [
    {
      "required": [
        "phone"
      ]
    },
    {
      "required": [
        "email"
      ]
    }
  ]
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "received"
      ]
    },
    "coverage_tier": {
      "type": "string",
      "enum": [
        "pre_ranked",
        "live_sourced"
      ]
    },
    "target_response": {
      "type": "string"
    },
    "target_response_guaranteed": {
      "type": "boolean"
    },
    "next_step": {
      "type": "string"
    }
  },
  "required": [
    "request_id",
    "status",
    "coverage_tier",
    "target_response",
    "target_response_guaranteed",
    "next_step"
  ],
  "additionalProperties": false
}

Read-only. Returns the current status of a request created with request_quotes. Requires the request_id and either the email or the phone number given on the request. It never returns the customer's details.

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "phone": {
      "type": "string"
    }
  },
  "required": [
    "request_id"
  ],
  "additionalProperties": false,
  "anyOf": [
    {
      "required": [
        "email"
      ]
    },
    {
      "required": [
        "phone"
      ]
    }
  ]
}

{
  "type": "object",
  "properties": {
    "request_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "request_id",
    "status",
    "message"
  ]
}