Start a quote request | Truvo Partners docs

curl -X POST https://api.truvo.com/v1/quote-requests \
     -H "Idempotency-Key: 3cadd765-fc58-4ddf-8fe5-6c62167b78cb" \
     -H "Truvo-Version: 2026-09-26" \
     -H "Authorization: Bearer <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "application": {
    "applicant": {
      "email": "alex@example.com",
      "first_name": "Test",
      "last_name": "Applicant One",
      "phone": "512-555-0123"
    },
    "credit_rating": "good",
    "current_insurance": {
      "carrier": "state_farm",
      "continuous_coverage_months": 12,
      "insured": true,
      "liability_limit": "100/300/100"
    },
    "drivers": [
      {
        "age_first_licensed": 18,
        "date_of_birth": "1990-04-12",
        "education": "bachelor_degree",
        "first_name": "Test",
        "gender": "female",
        "has_incidents_last_5_years": false,
        "last_name": "Applicant One",
        "marital_status": "married"
      }
    ],
    "garaging_address": {
      "city": "Austin",
      "line1": "100 Example Way",
      "line2": null,
      "postal_code": "78701",
      "state": "TX"
    },
    "protection": {
      "bodily_injury_per_accident_minor": 30000000,
      "bodily_injury_per_person_minor": 10000000,
      "property_damage_minor": 5000000
    },
    "residence_ownership": "owned",
    "vehicles": [
      {
        "annual_mileage": 8000,
        "collision_deductible_minor": 100000,
        "comprehensive_deductible_minor": 100000,
        "make": "Toyota",
        "model": "Camry",
        "ownership": "owned",
        "use": "pleasure",
        "vin": "SYNTHVIN000000001",
        "year": 2019
      }
    ]
  },
  "line": "personal_auto",
  "quote_disclosure_accepted": true,
  "quote_disclosure_version": "2026-10-06.1"
}'

{
  "id": "qreq_f09d1472f363261d325ba98ca1d965ee",
  "version": 1,
  "line": "personal_auto",
  "environment": "sandbox",
  "created_at": "2026-09-27T15:00:08.000Z",
  "updated_at": "2026-09-27T15:00:08.000Z",
  "status": "in_progress",
  "status_details": {
    "reason": "queued",
    "message": "The request is waiting to start.",
    "retry_action": null
  },
  "quotes": [],
  "market_outcomes": [],
  "assumptions": [
    {
      "path": "application.vehicles.0.driver_index",
      "value": 0,
      "source": "single_driver",
      "label": "Truvo assigns this vehicle to the only driver on the request."
    },
    {
      "path": "application.drivers.0.marital_status",
      "value": "single",
      "source": "auto_rating_fact",
      "label": "Truvo rates a married driver as single when no driver is listed as the applicant's spouse."
    }
  ],
  "next_actions": [
    {
      "id": "qreq_f09d1472f363261d325ba98ca1d965ee",
      "resource": "quote_request",
      "type": "read_status"
    },
    {
      "quote_request_id": "qreq_f09d1472f363261d325ba98ca1d965ee",
      "type": "request_assistance"
    }
  ]
}

Also available as the MCP tool start_quote_request.

Authentication

AuthorizationBearer

Your Truvo API key, sent as a bearer token. The prefix selects sandbox (trv_sandbox_) or live (trv_live_).

Headers

Request

This endpoint expects an object.

PersonalAutoQuoteRequestHttpBodyobjectRequired

RentersQuoteRequestHttpBodyobjectRequired

PetQuoteRequestHttpBodyobjectRequired

Response headers

Request-Idstringformat: "^req_[0-9a-f]{16}$"

The ID of this answer. An error body repeats it as request_id.

Truvo-Versionstringformat: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

The contract revision of this answer: the revision that the request named in Truvo-Version. A 404, and a refusal sent before Truvo knows your revision (401, 413, a 429 for failed authentication, and a 400 invalid_version), name the current revision and take its shape.

RateLimit-LimitintegerOptional

The calls this window allows, for the limit you're closest to reaching. The window is one minute or one UTC day. A fixed window allows a burst of up to twice the limit across a window edge.

RateLimit-RemainingintegerOptional

The calls left in the current window.

RateLimit-ResetintegerOptional

Seconds until the current window ends and the count resets.

Response

Starts a quote request for one line and one applicant.

idstringformat: "^qreq_[a-z0-9]{8,64}$"

The quote request ID, which starts with qreq_.

versioninteger<=9007199254740991

Rises with each change to the request: the start of its run, each new quote, and the final status. Send it as since_version to wait for the next change.

linestring

The insurance line.

environmentstring

The environment of the call: sandbox or live.

created_atdatetime

When Truvo created the quote request. The created_after and created_before list filters compare against it.

updated_atdatetime

When the quote request last changed. The updated_since list filter compares against it.

statusenum

Where the request stands. failed is an error on Truvo’s side and always says what to do next. incomplete is a finished result where carriers gave no final answer. Neither completed nor incomplete is an error. action_required is not used yet. Switch on it: a new value comes only in a new revision.

Allowed values:

status_detailsobject

Why the resource has this status. New reasons can arrive in any revision: show message, and give any switch on reason a default branch.

quoteslist of objects

The ID and the version of each quote. A request in progress already shows the quotes so far.

market_outcomeslist of objects

The carriers that Truvo asked, and how each answered.

assumptionslist of objects

The defaults that Truvo set before it asked carriers, and each stated value that Truvo rates differently, each with a path, a value, and a source. To change a default, send the fact. A rated value’s label says why Truvo rates it so.

next_actionslist of objects

What you can do next. Skip an action of a type that you don't know.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

413

Content Too Large Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error