Get quote results

POST /v1/quote-requests answers right away with 202 and a quote request in the queued status. Truvo then gets the quotes in the background, and you read the quote request to see the result.

Read the quote request

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

A read never starts a new rating run.

Hold the read open with Prefer: wait

Add Prefer: wait=N to hold the read open for up to N seconds, where N is a whole number from 0 to 20. The API answers as soon as the status is no longer queued or running, or when the time runs out. Without the header, it answers at once.

When the server can’t hold the request, it answers at once without Preference-Applied and with Retry-After. Wait that long before you poll again.

A value that isn’t valid gets 422 with the code invalid_input.

Know when to stop

queued and running mean the work is still going. Every other status is final, so stop reading when you see one. Between reads, the loop waits for the Retry-After seconds when the answer has that header, and for 1 second when the server didn’t hold the read open:

while true; do
  body=$(curl -s -D headers.txt "https://api.truvo.com/v1/quote-requests/$QUOTE_REQUEST_ID" \
    -H "Authorization: Bearer $TRUVO_API_KEY" \
    -H "Prefer: wait=20")
  state=$(printf '%s' "$body" | jq -r .status)
  if [ "$state" != "queued" ] && [ "$state" != "running" ]; then
    break
  fi
  retry_after=$(awk -F': ' 'tolower($1) == "retry-after" { print $2 + 0 }' headers.txt)
  if [ -n "$retry_after" ]; then
    sleep "$retry_after"
  elif ! grep -qi '^preference-applied:' headers.txt; then
    sleep 1
  fi
done
printf '%s\n' "$body"

The 60-second deadline

Each quote request has a 60-second deadline. Truvo stops collecting answers 60 seconds after it accepts the request, then finishes the request with the answers it has.

• A carrier that hasn’t answered by then reads no_answer in market_outcomes.
• If no carrier answered at all, the request ends failed, and its failure.code is no_quotes_by_deadline.
• A finished request never reopens. An answer that arrives after the deadline, or after the request finished, doesn’t change it.

Read the result

• completeness is pending, partial, or complete. A partial result can still be useful.
• quotes gives the ID and the version of each quote. To read one quote version, call GET /v1/quotes/{id}?version=.
• market_outcomes lists each carrier that Truvo asked, with how it answered: quote, decline, missing_information, failed, unknown, or no_answer. Each entry names the carrier in source.
• next_actions lists what you can do next.
• failure is null unless the request failed. Then it gives a code, no_quotes_by_deadline or quote_run_not_started, with a message and a retry_action. Both codes ask you to send the request again with a new Idempotency-Key.

A completed request with zero quotes isn’t a failure: a decline, or an answer with no offers, still completes. Check market_outcomes to see how each carrier answered.