List requests

GET /api/v1/deal-sets

The signed-in buyer's requests, one summary each.

Fact	Value
Availability	Available
Credential	The buyer's signed-in website session; An AI assistant the buyer approved, sending the access token she gave it. It sees only what the buyer allowed it to see
Rate limit	read: 120 per 60 s
Deadline	8 s. Past it, the read is cancelled and nothing partial is sent.

Query parameters

Name	Type	Description
`since`	string (ISO 8601 time)	Optional. An ISO 8601 time with a time zone, for example `2026-10-06T17:00:00Z`. Only requests with activity after that time are returned. This is a poll: it does not notify you. To read everything, start with `1970-01-01T00:00:00Z`. A value that is not in this form is refused with `invalid_request`, never answered with an empty list.

Response

200 with { "data": … }. Money is integer US cents, in fields named …Cents.

Field	Type	Description
`[].kind`	"deal_set" \| "single"	Which kind of entry this is: `deal_set` or `single`. A client MUST skip an entry whose kind it does not know.
`[].dealSetId`	string	Only when `kind` is "deal_set".
`[].href`	string	Our website's path for this set. Display text: its words may change; do not branch on it. Only when `kind` is "deal_set".
`[].car`	object
`[].car.year`	integer \| integer, nullable
`[].car.make`	string \| string, nullable
`[].car.model`	string \| string, nullable
`[].car.trim`	string, nullable	When `kind` is "deal_set": A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer. When `kind` is "single": A trim read from the listing, not from the buyer's own choice. Released to an AI assistant by the CEO's decision D37 (2026-10-08).
`[].car.exteriorColor`	string, nullable	A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer. Only when `kind` is "deal_set".
`[].car.interiorColor`	string, nullable	A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer. Only when `kind` is "deal_set".
`[].car.drivetrain`	string, nullable	A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer. Only when `kind` is "deal_set".
`[].car.powertrain`	string, nullable	A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer. Only when `kind` is "deal_set".
`[].buyerZip`	string, nullable	The buyer's own search ZIP (the same value as the results' `search.buyerZip`), returned only to the buyer's own session. Null for an AI assistant acting for the buyer. Only when `kind` is "deal_set".
`[].dealerCount`	integer, nullable	How many dealerships the search found for this set. Null for an AI assistant acting for the buyer (the count is third-party listing data). Counts of dealers who wrote back stay. Only when `kind` is "deal_set".
`[].summary`	object	Only when `kind` is "deal_set".
`[].summary.written`	integer	Only when `kind` is "deal_set".
`[].summary.waiting`	integer	Only when `kind` is "deal_set".
`[].summary.differentCar`	integer	Only when `kind` is "deal_set".
`[].summary.ended`	integer	Only when `kind` is "deal_set".
`[].summary.endedWithPrice`	integer	Only when `kind` is "deal_set".
`[].summary.closedWithPrice`	integer	Only when `kind` is "deal_set".
`[].lowestWrittenOtdCents`	integer, nullable	When `kind` is "deal_set": When `kind` is "single": The dealer's written out-the-door price in integer US cents, only when it is in writing; null otherwise. Same meaning as on a deal-set entry.
`[].lowestWrittenDistanceMiles`	number, nullable	Distance from the buyer ZIP in miles (third-party listing data). It is the hero row's distance, so before that dealership is unlocked or chosen it is the LOWER BOUND of the distance band (0, 10, 25, 50 or 100), not the distance; after, the exact distance. Null for an AI assistant acting for the buyer. Only when `kind` is "deal_set".
`[].needsYou`	integer	When `kind` is "deal_set": When `kind` is "single": 1 when the dealer asked the buyer something and is waiting, else 0.
`[].chosenLabels`	array of string	The dealers the buyer has chosen, as labels. For a connected assistant (a delegated agent) each is a description of the car (colour, year, model, trim, miles to the nearest 100, listed price), never the dealership's name; the buyer's own session sees the name once she has chosen. Display text: its words may change, and two entries can read the same. Display text: its words may change; do not branch on it. Only when `kind` is "deal_set".
`[].section`	"ready" \| "in_progress" \| "inactive"	Where the buyer's page places the request: `ready` = the dealership finished and sent an offer, `in_progress` = still active (it may already hold a written price), `inactive` = off the page. Whether a written price exists is `lowestWrittenOtdCents` (not null), whatever the section.
`[].memberIds`	array of string	Only when `kind` is "deal_set".
`[].latestActivityAt`	string, nullable	When `kind` is "deal_set": When `kind` is "single": The newest time this request changed (a time with a time zone), or null when none is known.
`[].changes`	object (optional)	What changed on this request since `since`. Only on a `since` call, and only for an account that was granted it.
`[].changes.hasWrittenPrice`	boolean	True when this request has a price in writing. A STATE, not an event: it does not say when the price became written, and it can be true on a request that was already written before `since`.
`[].changes.newReplies`	one of	Dealership replies on this request after `since`: `none`, `new` (a count and a time) or `could_not_check` (the request could not be read just now; it is NOT the same as none).
`[].changes.newReplies.status`	"none" \| "new" \| "could_not_check"
`[].changes.newReplies.count`	integer	How many dealership replies arrived after `since`. A number only: never what a reply said.
`[].changes.newReplies.latestAt`	string	When the most recent of them arrived (a time with a time zone, our own receipt time).
`[].changes.ended`	boolean	True when this request has ended. A STATE, not an event: it carries no time and does not mean it ended after `since`.
`[].id`	string	This request's own id. It is a PRICE-CHECK id, not a deal-set id: GET /api/v1/deal-sets/{id} does not accept it. Only when `kind` is "single".
`[].dealerLabel`	string, nullable	The dealership. For a connected assistant (a delegated agent) it is a description of the car (year, model, trim), never the dealership's name; for the buyer's own session it is the name, or null when the buyer has not seen it yet. Display text: its words may change. Display text: its words may change; do not branch on it. Only when `kind` is "single".

Response headers

Name	Description
`Ridekick-As-Of`	Sent only when `since` was sent. The time to pass as `since` on your next call. It is set slightly before this read began, so an entry can come back twice but is never skipped.
`Ridekick-More`	Sent on every successful list answer. On a plain call `true` means an ACTIVE request was left out (ended ones are never counted: they come only with `since`). On a `since` page it means more entries remain. If that cannot be told, it is `true`. Keep reading until it is `false`.

Notes

Each entry has a kind, a closed set: deal_set or single. A client MUST skip an entry whose kind it does not know.
A single entry's id is a price-check id, not a deal-set id. GET /api/v1/deal-sets/{id} does not accept it and answers its normal 404.
To read everything, call with since=1970-01-01T00:00:00Z, then repeat with since set to the Ridekick-As-Of you got, until Ridekick-More is false.
An entry can appear on more than one page. Keep one entry per id and kind.
section is where the buyer's page places the request: ready is a request the dealership finished and sent an offer for, in_progress is one still active (it may already hold a written price), inactive is one off the page. Whether a written price exists is lowestWrittenOtdCents (not null), whatever the section.
On a since call, an assistant whose buyer was granted it also gets a changes object on each entry, saying WHAT changed: hasWrittenPrice (a state: the request has a price in writing; it does not say when it became written), newReplies (none, new with a count and the time we received the most recent one, or could_not_check; never what a reply said) and ended (a state, never a time). Anyone else gets exactly the entry described above. A plain call never has changes.
A plain call (no since) returns the buyer's ACTIVE requests: the grid requests that have not ended (up to 12) and the newest 25 requests to one dealership that are not inactive. Ridekick-More is true only when an active request was left out. Ended (inactive) requests, including a request whose price is not in writing, come only by paging with since.

Example call

bash

curl -X GET "https://www.ridekick.com/api/v1/deal-sets" \
  -H "Authorization: Bearer $RIDEKICK_TOKEN"

javascript

const res = await fetch("https://www.ridekick.com/api/v1/deal-sets", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.RIDEKICK_TOKEN}` },
});
const { data } = await res.json();

python

import os
import requests

res = requests.get("https://www.ridekick.com/api/v1/deal-sets", headers={"Authorization": f"Bearer {os.environ['RIDEKICK_TOKEN']}"})
data = res.json()["data"]

Example

json

{
  "data": [
    {
      "kind": "deal_set",
      "dealSetId": "0b6f3c2e-9d41-4c7a-8e15-3a2f7c9d1e04",
      "href": "/negotiations/deal-sets/0b6f3c2e-9d41-4c7a-8e15-3a2f7c9d1e04",
      "car": {
        "year": 2026,
        "make": "Testmake",
        "model": "Testmodel",
        "trim": "Sport",
        "exteriorColor": "Blue",
        "interiorColor": "Black",
        "drivetrain": "AWD",
        "powertrain": "hybrid"
      },
      "buyerZip": "94110",
      "dealerCount": 5,
      "summary": {
        "written": 2,
        "waiting": 1,
        "differentCar": 1,
        "ended": 1,
        "endedWithPrice": 0,
        "closedWithPrice": 0
      },
      "lowestWrittenOtdCents": 3812345,
      "lowestWrittenDistanceMiles": 12.4,
      "needsYou": 1,
      "chosenLabels": [],
      "section": "ready",
      "memberIds": [
        "neg-1",
        "neg-2"
      ],
      "latestActivityAt": "2026-09-29T12:00:00.000Z"
    }
  ]
}

Errors

Status	Code	Means
404	`not_found`	No such resource, or not yours. Also answered while the endpoint is not turned on for you. Never 403: whether another buyer's resource exists is not disclosed.
401	`unauthenticated`	Signed out, or the credential was not accepted: an access token that is not valid, or an Authorization header that is not a Ridekick access token.
503	`auth_unverifiable`	Sign-in could not be confirmed. This is not the same as signed out.
503	`unavailable`	The service did not answer right now, so nothing was returned or sent. Try again in a moment, and wait the number of seconds in `Retry-After` when it is present.
429	`rate_limited`	Too many requests from this principal in the window.
403	`insufficient_scope`	The credential does not include the scope this endpoint needs. The WWW-Authenticate header names the required scope.
400	`invalid_request`	The request body or a header failed validation. An out-of-range value is refused, not adjusted: what you asked is never silently changed.
500	`internal`	Something failed on our side. The response carries no data.

Last updated October 9, 2026