Quickstart | Truvo Platform docs

This guide walks through one personal auto quote in the sandbox. Sandbox quotes are synthetic, so the prices you see aren’t carrier prices.

Before you start

You need a sandbox key. Create one on the Developer sandbox page of the portal. Sandbox keys start with trv_sandbox_. Put yours in an environment variable so the examples below can use it:

export TRUVO_API_KEY="trv_sandbox_..."

Every request goes to https://api.truvo.com/v1/ and sends the key as a bearer token. Keys and environments covers both in more detail.

Check what your key can do

Start by asking the API what your key can do:

curl https://api.truvo.com/v1/capabilities \
  -H "Authorization: Bearer $TRUVO_API_KEY"

The response gives the line, the environment, a JSON Schema of the facts the line requires, and the action types your key can use.

Start a quote request

Now send the facts for one line. This is a personal auto request with one driver and one vehicle, and every value in it is synthetic. In a new sandbox, this request returns one quote.

curl -X POST https://api.truvo.com/v1/quote-requests \
  -H "Authorization: Bearer $TRUVO_API_KEY" \
  -H "Idempotency-Key: quickstart-quote-01" \
  -H "Content-Type: application/json" \
  -d '{
    "line": "personal_auto",
    "consent_receipt_id": "consent-auto-one-owned",
    "application": {
      "applicant": {
        "name": { "first_name": "Test", "last_name": "Applicant One" },
        "email": "alex@example.com",
        "phone": "5550100000"
      },
      "garaging_address": {
        "line1": "100 Example Way",
        "line2": null,
        "city": "Austin",
        "state": "TX",
        "postal_code": "78701"
      },
      "drivers": [
        {
          "name": { "first_name": "Test", "last_name": "Applicant One" },
          "date_of_birth": "1990-04-12",
          "gender": "female"
        }
      ],
      "vehicles": [
        {
          "vin": "SYNTHVIN000000001",
          "year": 2019,
          "make": "Toyota",
          "model": "Camry",
          "ownership": "owned",
          "use": "pleasure",
          "annual_mileage": 8000,
          "comprehensive_deductible_minor": 100000,
          "collision_deductible_minor": 100000
        }
      ],
      "protection": {
        "bodily_injury_per_person_minor": 10000000,
        "bodily_injury_per_accident_minor": 30000000,
        "property_damage_minor": 5000000
      }
    }
  }'

A few things to notice in the body:

consent_receipt_id is the ID of the applicant’s consent for Truvo to get quotes for them. It covers quoting only. A credit check and contact each take their own receipt. See Consent receipts.
For auto, driver 1 is the named insured. The API takes the applicant’s date of birth from driver 1.
Money values are integers in minor units, so 10000000 is $100,000.

The API answers with 202 and a quote request in the queued status. Save its id, which starts with qreq_. You’ll need it in the next step.

Wait for the result

Truvo gets the quotes in the background, so read the quote request until it’s done. The Prefer: wait=20 header asks the API to hold the read open for up to 20 seconds.

curl https://api.truvo.com/v1/quote-requests/qreq_... \
  -H "Authorization: Bearer $TRUVO_API_KEY" \
  -H "Prefer: wait=20"

If the status is still queued or running, read it again. Once it’s completed, the quotes list gives the ID and the version of each quote. Get quote results covers the other final statuses.

Read a quote

curl https://api.truvo.com/v1/quotes/qt_... \
  -H "Authorization: Bearer $TRUVO_API_KEY"

A quote gives the price, the coverage, the availability, the next actions, and the evidence. In the sandbox, the evidence label is mock, and the coverage conditions include Sandbox premium. Not a carrier price.

To test other results, such as a decline or several quotes, pick a sandbox scenario.

Next steps

Retry safely

Retry a create without starting a second request.

Handle errors

Read the error envelope and its retry action.

API reference

Every operation and its schemas.