> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.truvo.com/llms.txt.

# Quickstart

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](https://partners.truvo.com/developers) page of the portal. Sandbox keys start with `trv_sandbox_`. Put yours in an environment variable so the examples below can use it:

```bash
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](/guides/authentication) covers both in more detail.

### Check what your key can do

Start by asking the API what your key can do:

```bash
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.

```bash
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](/guides/truvo#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.

```bash
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](/guides/polling) covers the other final statuses.

### Read a quote

```bash
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](/guides/sandbox-scenarios).

## Next steps

#### [Retry safely](/guides/request-keys)

Retry a create without starting a second request.

#### [Handle errors](/guides/errors)

Read the error envelope and its retry action.

#### [API reference](/api-reference)

Every operation and its schemas.