quote-documentation.md

POST /quote

This endpoint calculates a price quote for a vehicle service based on vehicle details and the time of service. It uses a rules-based engine for exact matches and falls back to a Generative AI model (LLM) to handle ambiguous or incomplete data.

• prod: https://phoenix-crm-api.herokuapp.com

• staging: https://phoenix-staging-data-3d6054f8c3ef.herokuapp.com

• URL: /quote

• Method: POST

• Content-Type: application/json

---

Request Body

The body of the request must be a JSON object containing the vehicle and service details.

Field	Type	Required	Description
year	number	Yes	The year of the vehicle (e.g., 2018).
make	string	Yes	The manufacturer of the vehicle (e.g., "Honda"). The LLM can handle common misspellings or abbreviations (e.g., "Chevy").
model	string	Yes	The model of the vehicle (e.g., "Accord").
service_type	string	No	The type of service requested (e.g., "unlock"). While not currently used in the pricing logic, it is passed to the LLM for context and may be used in the future.
service_time	string or number	No	The time the service is requested. This field is highly flexible. If omitted, no time surcharge is applied. Accepted Formats: - ISO 8601 String: "2023-10-27T22:30:00.000Z" - Natural Language: "now", "tonight at midnight", "at 4am" - Unix Timestamp: 1698463800000

---

Success Response (200 OK)

A successful request returns a JSON object containing the price quote and its breakdown.

Field	Type	Description
ok	boolean	true for a successful quote calculation.
source	string	Indicates the source of the quote. Either "rules" for an exact match from the pricing tables or "llm" for a quote generated by the AI model.
quote	number	The final calculated price for the service.
currency	string	The currency of the quote (e.g., "USD").
vehicle_class	string	The vehicle category determined by the service (e.g., "Full-Size Car").
confidence	number	A score from 0.0 to 1.0 indicating the confidence in the quote. A 1.0 means it was a perfect match from the rules engine. A lower score indicates an LLM-inferred result.
breakdown	array	An array of objects detailing the components of the final quote, such as base price, time surcharge, and luxury uplift.
notes	string	Additional information or context, typically provided by the LLM when it has to normalize data or make an assumption (e.g., "Normalized 'Chevy' to 'Chevrolet'.").

---

Error Responses

• 400 Bad Request: This error is returned if required fields (year, make, model) are missing from the request body.

  {
    "ok": false,
    "error": "Missing required fields: year, make, and model are required."
  }

• 500 Internal Server Error: This error is returned if the service encounters an unrecoverable issue during quote calculation (e.g., the LLM fails and no rules-based match is found).

  {
    "ok": false,
    "error": "An internal server error occurred.",
    "details": "LLM quote generation failed."
  }

---

curl Examples

1. Rules-Based Quote (Exact Match)

This request will be successfully handled by the rules engine.

curl -X POST 'https://phoenix-crm-api.herokuapp.com/quote' \
-H "Content-Type: application/json" \
-d '{
  "year": 2018,
  "make": "Honda",
  "model": "Accord",
  "service_time": "2025-10-03T22:30:00.000Z"
}'

2. LLM Fallback Quote (Typo in Make)

This request will fail the rules-based lookup and be handled by the LLM.

curl -X POST 'https://phoenix-crm-api.herokuapp.com/quote' \
-H "Content-Type: application/json" \
-d '{
  "year": 2018,
  "make": "Cvehy",
  "model": "Tahoe",
  "service_time": "2025-10-03T22:30:00.000Z"
}'

3. LLM Fallback with Natural Language Time

This request demonstrates using a plain English string for service_time. The upstream LLM call will normalize this to a timestamp before the quote is calculated.

curl -X POST 'https://phoenix-crm-api.herokuapp.com/quote' \
-H "Content-Type: application/json" \
-d '{
  "year": 2022,
  "make": "Ford",
  "model": "F-150",
  "service_time": "tomorrow at 3am"
}'