Truvo Buyer API

Integration guide for RTB ping/post and click-lead endpoints

Overview

The Truvo Buyer API supports two integration patterns:

• RTB Ping/Post — Real-time bidding. Send a ping with lead data, receive a bid, then deliver the full lead via post.
• Click Leads — Direct ingest. POST lead data and receive a click_id for tracking.

Authentication

All production endpoints require an API key sent via the X-API-Key header:

X-API-Key: your-vendor-api-key

Keys are provisioned per-vendor. Contact tech@truvoinsure.com to request credentials.

Base URL

https://buyer.truvoinsure.com

RTB Ping/Post Flow

Endpoints

RTB Ping/Post

Click Leads

Ping Request

POST /api/quotewizard/ping

curl -X POST https://buyer.truvoinsure.com/api/quotewizard/ping \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
  "Contact": {
    "FirstName": "Jane",
    "LastName": "Doe",
    "State": "TX",
    "Zip": "75001",
    "City": "Dallas"
  },
  "Drivers": [{
    "BirthDate": "1990-05-15",
    "Gender": "Female",
    "LicenseStatus": "Valid",
    "CreditRating": "Good"
  }],
  "Vehicles": [{
    "Year": 2021,
    "Make": "Honda",
    "Model": "Civic"
  }],
  "Insurance": {
    "CurrentlyInsured": "Yes",
    "InsuranceCarrier": "GEICO"
  },
  "Additional": {
    "OwnHome": "Yes",
    "DriverCount": 1,
    "VehicleCount": 1
  },
  "Tracking": {
    "Test": false,
    "LeadId": "ext-lead-123",
    "ConsumerIP": "203.0.113.42"
  }
}'

import requests

resp = requests.post(
    "https://buyer.truvoinsure.com/api/quotewizard/ping",
    headers={
        "X-API-Key": "your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "Contact": {"FirstName": "Jane", "LastName": "Doe", "State": "TX", "Zip": "75001", "City": "Dallas"},
        "Drivers": [{"BirthDate": "1990-05-15", "Gender": "Female", "LicenseStatus": "Valid", "CreditRating": "Good"}],
        "Vehicles": [{"Year": 2021, "Make": "Honda", "Model": "Civic"}],
        "Insurance": {"CurrentlyInsured": "Yes", "InsuranceCarrier": "GEICO"},
        "Additional": {"OwnHome": "Yes", "DriverCount": 1, "VehicleCount": 1},
        "Tracking": {"Test": False, "LeadId": "ext-lead-123", "ConsumerIP": "203.0.113.42"},
    },
)
print(resp.json())
# {"status": "SUCCESS", "bid": 5.0, "pingId": "QW-M1XYZ-A3B2C1"}

const resp = await fetch("https://buyer.truvoinsure.com/api/quotewizard/ping", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    Contact: { FirstName: "Jane", LastName: "Doe", State: "TX", Zip: "75001", City: "Dallas" },
    Drivers: [{ BirthDate: "1990-05-15", Gender: "Female", LicenseStatus: "Valid", CreditRating: "Good" }],
    Vehicles: [{ Year: 2021, Make: "Honda", Model: "Civic" }],
    Insurance: { CurrentlyInsured: "Yes", InsuranceCarrier: "GEICO" },
    Additional: { OwnHome: "Yes", DriverCount: 1, VehicleCount: 1 },
    Tracking: { Test: false, LeadId: "ext-lead-123", ConsumerIP: "203.0.113.42" },
  }),
});
const data = await resp.json();
// { status: "SUCCESS", bid: 5.0, pingId: "QW-M1XYZ-A3B2C1" }

Ping Response

{
  "status": "SUCCESS",
  "bid": 5.00,
  "pingId": "QW-M1XYZ-A3B2C1"
}

A bid of 0 means no bid — do not send a post for this lead.

Post Request

POST /api/quotewizard/post

Include the PingId from the ping response along with the full lead payload:

curl -X POST https://buyer.truvoinsure.com/api/quotewizard/post \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
  "PingId": "QW-M1XYZ-A3B2C1",
  "Contact": {
    "FirstName": "Jane",
    "LastName": "Doe",
    "Email": "jane.doe@example.com",
    "Phone": "2145551234",
    "Address": "123 Main St",
    "City": "Dallas",
    "State": "TX",
    "Zip": "75001"
  },
  "Drivers": [{
    "BirthDate": "1990-05-15",
    "Gender": "Female",
    "LicenseStatus": "Valid",
    "MaritalStatus": "No",
    "CreditRating": "Good",
    "DUI": "No",
    "DoesRequireSR22": "No",
    "IncidentCount": 0
  }],
  "Vehicles": [{
    "VIN": "1HGCV1F34LA000001",
    "Year": 2021,
    "Make": "Honda",
    "Model": "Civic",
    "SubModel": "LX"
  }],
  "Insurance": {
    "CurrentlyInsured": "Yes",
    "InsuranceCarrier": "GEICO",
    "InsuredTimeframe": "TwelveOrMoreMonths"
  },
  "Additional": {
    "OwnHome": "Yes",
    "AutoHomeBundle": "No",
    "MilitaryStatus": "No",
    "DriverCount": 1,
    "VehicleCount": 1
  },
  "Tracking": {
    "Test": false,
    "LeadId": "ext-lead-123",
    "TrustedForm": "https://cert.trustedform.com/abc123",
    "ConsumerIP": "203.0.113.42",
    "SubId": "campaign-456"
  }
}'

Post Response

{"status": "SUCCESS"}

Or if rejected:

{"status": "REJECT"}

Payload Reference

Contact

Drivers[]

Vehicles[]

Insurance

Additional

Tracking

Error Handling

Testing

Set "Test": true in the Tracking object to send test pings. Test pings always return a bid of $0.00 and won't create real leads.