API reference
The Truvo API uses JSON request and response bodies, standard HTTP status codes, and bearer-key authentication. If you’re new to it, start with the Quickstart, which shows a complete request.
Base URL
The sandbox and live use the same base URL. Your key picks the environment.
Authentication
Send your key in the Authorization header as a bearer token. Sandbox keys start with trv_sandbox_, and live keys start with trv_live_. See Keys and environments.
Request keys
Starting a quote request, creating a webhook subscription, rotating its secret, sending a test event, and replaying a delivery require an Idempotency-Key header, so a retry doesn’t start a second request. A key replays for at least 24 hours. Reads don’t take a key. See Retry safely with request keys.
Asynchronous quote requests
Starting a quote request returns 202 right away. Read the quote request until its status is no longer in_progress. Prefer: wait=N (0 to 20 seconds) holds each read open until the request changes, counted from the since_version you send. Webhooks can push each change instead. See Get quote results.
After a purchase
The customer buys through a quote’s continue_on_carrier_site link. The API has no policy object, so it doesn’t read or change a policy. For a change to a policy, a cancellation or a claim, the customer contacts Truvo support at support@truvo.com, and a person handles it.
Errors
Every error uses one envelope with a code, a message, the fields at fault, and a retry action. See Errors.
Versions
Every request to an API operation names its contract revision in the Truvo-Version header, and the answer names the same revision. /v1/mcp and the discovery documents don’t need the header. A breaking change ships only in a new revision. See Versions and changes and the changelog.