Voice Quote API Endpoint

This document provides instructions for using the /voice-quote API endpoint. This endpoint is designed to provide a price quote for vehicle services based on a spoken service_type, making it ideal for voice bot and IVR integrations.

Endpoint

POST /voice-quote

Request Body

The request body must be a JSON object with the following fields:

Field	Type	Description	Required
year	Integer	The vehicle's year of manufacture.	Yes
make	String	The make of the vehicle (e.g., "Toyota", "Ford").	Yes
model	String	The model of the vehicle (e.g., "Camry", "F-150").	Yes
service_time	String	An ISO 8601 formatted timestamp or a natural language string representing the desired service time.	No
service_type	String	The name of the service being requested (e.g., "Unlock", "Jump-Start").	Yes

Example Request

{
  "year": 2022,
  "make": "Honda",
  "model": "Civic",
  "service_time": "today at 3pm",
  "service_type": "Tire Change"
}

Responses

Success Response

A successful request will return a 200 OK status code and a JSON object containing the price quote and a breakdown of the costs.

Example Success Response:

{
    "ok": true,
    "source": "rules",
    "quote": 125,
    "currency": "USD",
    "vehicle_class": "Sedan",
    "confidence": 1.0,
    "breakdown": [
        {
            "label": "Base price",
            "amount": 90
        },
        {
            "label": "Time surcharge",
            "amount": 35
        }
    ],
    "notes": null
}

Error Responses

If the request is invalid or an error occurs, the API will return an appropriate error code and a JSON object with details about the error.

400 Bad Request

Returned when a required field is missing from the request body.

{
    "ok": false,
    "error": "Missing required field: service_type is required."
}

404 Not Found

Returned when the provided service_type does not match any of the available services.

{
    "ok": false,
    "error": "Service with name \"Tire Swap\" not found."
}

500 Internal Server Error

Returned when an unexpected error occurs on the server.

{
    "ok": false,
    "error": "An internal server error occurred.",
    "details": "Error message from the server."
}