warranties.followup_queue

List every warranty still waiting on its validation inspection

Read-onlyRead budget

REST

Shipping

POST /api/v1/warranties/followup_queue

MCP tool

Live

warranties.followup_queue

Exposed on: REST API · Shop MCP server · Claude connector · Dash (in-app copilot) · Zapier. Part of the Warranties domain.

Operating contract

THE CALLS THE SHOP OWES. A warranty issued with a follow-up policy is PROVISIONAL until the car comes back and somebody looks at it — and every row here is a customer who thinks they are covered and is not yet.

SOONEST-DUE FIRST, deliberately, because this is a work queue rather than a ledger. The warranty that has been provisional longest is the customer most likely to have forgotten and the cover that has been in limbo longest.

to_book IS TODAY'S CALL LIST — nothing is booked at all. booked is waiting on the car and needs nobody. overdue is past due plus its grace period, booked or not, and those are the ones where the cover is genuinely at risk.

NOTHING EXPIRES A WARRANTY AUTOMATICALLY out of this queue. A shop's provisional cover is not voided by a sweep; it waits until somebody validates it or the shop decides otherwise.

AN EMPTY QUEUE HAS TWO MEANINGS. A shop whose warranties carry no follow-up policy — every warranty issued before the feature, and every shop outside its ring — has an empty queue because there is nothing to validate, not because it is up to date.

TRUNCATION: at most a hundred rows come back and omitted says how many more are waiting. The counts above are of the returned page, so a non-zero omitted means the shop is further behind than they say.

Who may call it

Permission: customers.accessThe caller must hold Customers at the ACT level. A read-only dashboard grant on the same section is refused.
Plan: Every planNo plan gate. Available on every Service VIN plan.
Retries: naturalNaturally idempotent — running it twice leaves the same world as running it once. A retrying integration needs no key.
Rate class: readCounted against the read budget — the widest of the four.

Partial answers

omitted is how many matching records are not in the response, and 0 is a real answer meaning you have all of them. There is no cursor here — narrow the filter instead.

Do not summarise from a truncated response

When `omitted` is not 0 there are more warranties awaiting validation than were returned. Raise `limit`, or set `overdue_only` to work the ones whose cover is actually at risk first.

Input

Field	Type	Description
overdue_only	boolean	True returns only the ones past due plus their grace period.
limit	integer1–100	How many to return, 1-100, soonest-due first. Defaults to 50. Default: `50`

Output

Field	Type	Description
to_book	number	—
booked	number	—
overdue	number	—
items	object[]	—
items[].id	string	—
items[].number	string	—
items[].type	string	—
items[].coverage	string \| null	—
items[].stage	string	—
items[].due_on	string \| null	—
items[].overdue	boolean	—
items[].customer_id	string	—
items[].customer_name	string	—
items[].vehicle	string \| null	—
items[].job_id	string \| null	—
total	number	—
omitted	number	—

Examples

Built from this capability's own schema — required fields and the ones carrying a default, and nothing invented. Paste one and it validates.

curl

export SERVICEVIN_API_KEY=svk_live_…

curl -X POST https://www.servicevin.com/api/v1/warranties/followup_queue \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":50}'

TypeScript (fetch)

const res = await fetch("https://www.servicevin.com/api/v1/warranties/followup_queue", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "limit": 50
  }),
});

// Success and failure are both envelopes. Switch on error.code, never
// on error.message — the codes are stable, the messages are for people.
const payload = await res.json();
if (!res.ok) throw new Error(payload.error.code);
const data = payload.data;

Python (requests)

import os, requests

res = requests.post(
    "https://www.servicevin.com/api/v1/warranties/followup_queue",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "limit": 50
},
    timeout=30,
)
payload = res.json()
if not res.ok:
    raise RuntimeError(payload["error"]["code"])
data = payload["data"]

MCP tools/call — https://www.servicevin.com/api/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "warranties.followup_queue",
    "arguments": {
      "limit": 50
    }
  }
}

Refusals

The four gates run in this order on every surface, and the order is not arbitrary — see Authentication.

Status	Code	When
404	`not_found`	The id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
403	`forbidden`	This login does not hold customers.access.
422	`validation_error`	An argument was wrong. The message names the field.
429	`rate_limited`	Too many read calls. Back off and retry.
500	`internal_error`	Something failed on our side. Nothing was changed.

Operating contract#

Who may call it#

Partial answers#

Input#

Output#

Examples#

Refusals#