Requests
A request is one ask to several dealers, with the prices that come back. The API calls it a deal set: the paths are /api/v1/deal-sets, and its id is dealSetId.
The two endpoints
GET /api/v1/deal-sets returns a summary per request. GET /api/v1/deal-sets/{id} returns one request's ranked results. See List requests and Get a request.
Ranking
Rows are ranked by written out-the-door price, lowest first within each trim, for the same car. The hero is the lowest price in the first group.
Anonymity
Until the buyer chooses a dealer, a row is labelled by its car, not by the dealership. A hidden row carries no dealer name, contact, listing URL, VIN or image.
A connected assistant (a delegated agent) ALWAYS gets a description of the car (colour, year, model, trim, miles to the nearest 100 and the listed price; a part we do not have is left out) in label, on every field that labels a dealer: the rows, the hero, the questions and drafts that need the buyer, and chosenLabels. It never gets a dealership's name, even for a dealer the buyer chose. The buyer's own session sees the name once she has unlocked or chosen the dealer. The examples on this page show the buyer-session shape; an assistant receives the same fields with every label as a description of the car. Two rows can read the same: refer to a row by rowKey, never by its label.
Money
Money is integer US cents, in fields named …Cents.
What needs the buyer
needsYou lists items waiting on the buyer, each with a kind of question or draft.
Example
{
"data": {
"dealSetId": "0b6f3c2e-9d41-4c7a-8e15-3a2f7c9d1e04",
"car": {
"year": 2026,
"make": "Testmake",
"model": "Testmodel",
"trim": "Sport",
"exteriorColor": "Blue",
"interiorColor": "Black",
"drivetrain": "AWD",
"powertrain": "hybrid"
},
"search": {
"buyerZip": "94110",
"radiusMiles": 50
},
"counts": {
"written": 1,
"waiting": 1,
"differentCar": 1,
"ended": 1,
"endedWithPrice": 1,
"closedWithPrice": 0,
"total": 4,
"needsYou": 2
},
"headerLine": "1 written price, 1 waiting",
"hero": {
"rowKey": "neg-1",
"label": "Dealer 1",
"otdCents": 3800000,
"sellingPriceCents": 3500000,
"taxesAndFeesCents": 300000,
"listedAtCents": 3650000,
"writtenAt": "2026-09-28T13:00:00.000Z",
"distanceMiles": 12.4,
"distanceBand": "10 to 25 miles",
"trim": "Sport",
"gapToNextCents": 45000,
"canChoose": true,
"canUnlock": false,
"chosen": false
},
"ranked": [
{
"trim": "Sport",
"rows": [
{
"rowKey": "neg-1",
"label": "Dealer 1",
"hidden": true,
"chosen": false,
"archived": false,
"state": "written",
"ended": null,
"statusLabel": "Written price",
"otdCents": 3800000,
"sellingPriceCents": 3500000,
"listedAtCents": 3650000,
"writtenAt": "2026-09-28T13:00:00.000Z",
"gapToLowestCents": 0,
"canChoose": true,
"canUnlock": false,
"quotedTrim": "Sport",
"distanceMiles": 12.4,
"distanceBand": "10 to 25 miles",
"priceCheckHref": null,
"isVerifiedPartner": true
}
]
}
],
"needsYou": [
{
"kind": "question",
"rowKey": "neg-2",
"label": "Dealer 2",
"promptId": "prompt-1",
"category": "trade_in",
"heading": "A question about your trade-in",
"question": "Do you have a trade-in?",
"answerMode": "freeform",
"otdCents": 3900000
},
{
"kind": "draft",
"rowKey": "neg-3",
"label": "Dealer 3",
"requestId": "req-1",
"preview": "A reply we drafted.",
"previewComplete": true
}
],
"everyoneElse": {
"waiting": [
{
"rowKey": "neg-2",
"label": "Dealer 2",
"hidden": true,
"chosen": false,
"archived": false,
"state": "waiting",
"ended": null,
"statusLabel": "Waiting",
"otdCents": null,
"sellingPriceCents": null,
"listedAtCents": 3650000,
"writtenAt": null,
"gapToLowestCents": null,
"canChoose": false,
"canUnlock": false,
"quotedTrim": "Sport",
"distanceMiles": 12.4,
"distanceBand": "10 to 25 miles",
"priceCheckHref": null,
"isVerifiedPartner": true
}
],
"differentCar": [
{
"rowKey": "neg-3",
"label": "Dealer 3",
"hidden": true,
"chosen": false,
"archived": false,
"state": "different_car",
"ended": null,
"statusLabel": "Different car",
"otdCents": 3800000,
"sellingPriceCents": 3500000,
"listedAtCents": 3650000,
"writtenAt": "2026-09-28T13:00:00.000Z",
"gapToLowestCents": null,
"canChoose": false,
"canUnlock": false,
"quotedTrim": "Base",
"distanceMiles": 12.4,
"distanceBand": "10 to 25 miles",
"priceCheckHref": null,
"isVerifiedPartner": true
}
],
"ended": [
{
"rowKey": "neg-4",
"label": "Dealer 4",
"hidden": true,
"chosen": false,
"archived": false,
"state": "ended",
"ended": "sold",
"statusLabel": "Sold",
"otdCents": 3800000,
"sellingPriceCents": 3500000,
"listedAtCents": 3650000,
"writtenAt": "2026-09-28T13:00:00.000Z",
"gapToLowestCents": null,
"canChoose": false,
"canUnlock": false,
"quotedTrim": "Sport",
"distanceMiles": 12.4,
"distanceBand": "10 to 25 miles",
"priceCheckHref": null,
"isVerifiedPartner": true
}
],
"archived": []
}
}
}Last updated