Skip to main content
Documentation
Service VIN developer & AI platformGetting startedAuthenticationPaginationIdempotencyRate limitsErrorsWebhooks & signature verificationConnecting ClaudeRecipesMCP servers & the Claude connectorREST resource referenceCapability indexCustomers capabilitiesVehicles capabilitiesLeads capabilitiesWarranties capabilitiesQuotes capabilitiesInvoices capabilitiesPayments capabilitiesServices capabilitiesJobs capabilitiesCalendar capabilitiesScheduling capabilitiesStaff capabilitiesInventory capabilitiesComms capabilitiesTasks capabilitiesShop capabilitiesDocuments capabilitiesKnowledge capabilitiesReports capabilitiesBooking capabilitiesForms capabilitiesMarketing capabilitiesReviews capabilitiesAutomations capabilitiesIntegrations capabilitiesChangelogSearch

Reports

reports.install

Read the installer and film-usage report for a period
Read-onlyExpensive budget

REST

Shipping
POST /api/v1/reports/install

MCP tool

Live
reports.install

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

Operating contract

How the floor performed: revenue and booked hours per installer, and what the shop's film actually cost it — fitted, scrapped, and the waste percentage between them.

waste_pct IS THE NUMBER WORTH RAISING. Scrapped film is money the shop spent and cannot bill, and a waste percentage climbing over time is a training problem or a template problem long before anybody notices it in the margin.

MATERIAL COST INCLUDES SCRAP, deliberately, and the same definition is used by Job P&L and the inventory valuation. Film the shop cut and threw away is money it spent; leaving it out would understate every material figure on every other report.

by_installer revenue is the net revenue of the invoices behind that person's jobs. It is NOT a performance score: a shop that puts its most experienced installer on the difficult low-margin work will see them look worse here, and saying so is part of reporting it honestly.

The unassigned bucket is real work with nobody on it. A large unassigned row means the shop is not recording who did what, and every other figure in this read is weaker for it.

truncated is a flag rather than a count: when it is true a row cap bit and every figure on this response UNDERCOUNTS. Narrow the range and ask again, and say the period could not be read in full rather than quoting the totals.

Who may call it

Permission
reports.accessThe caller must hold Reports & insights 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
expensiveCounted against the expensive budget — a model call, a document render or a fan-out scan.

Partial answers

truncated 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

`truncated` is a flag rather than a count: when it is true a row cap bit and every figure on this response UNDERCOUNTS. Narrow the range and ask again, and say the period could not be read in full rather than quoting the totals.

Input

FieldTypeDescription
rangestring

The window: 7d, 30d, 90d, 12mo, ytd or all. Defaults to 90d.

Default: "90d"One of: 7d, 30d, 90d, 12mo, ytd, all

Output

FieldTypeDescription
rangestring

—

currencystring

—

truncatedboolean

—

filmobject

—

film.feet_usednumber

—

film.waste_feetnumber

—

film.waste_pctnumber | null

—

film.costnumber

—

film.job_costnumber

—

film.waste_costnumber

—

film.jobs_costednumber

—

by_installerobject[]

—

by_installer[].installerstring

—

by_installer[].unassignedboolean

—

by_installer[].revenuenumber

—

by_installer[].hoursnumber

—

by_installer[].jobsnumber

—

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/reports/install \
  -H "Authorization: Bearer $SERVICEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"range":"90d"}'

TypeScript (fetch)
const res = await fetch("https://www.servicevin.com/api/v1/reports/install", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SERVICEVIN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "range": "90d"
  }),
});

// 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/reports/install",
    headers={"Authorization": f"Bearer {os.environ['SERVICEVIN_API_KEY']}"},
    json={
    "range": "90d"
},
    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": "reports.install",
    "arguments": {
      "range": "90d"
    }
  }
}

Refusals

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

StatusCodeWhen
404not_foundThe id is unknown, or the feature is not enabled for this account. Deliberately the same answer for both.
403forbiddenThis login does not hold reports.access.
422validation_errorAn argument was wrong. The message names the field.
429rate_limitedToo many expensive calls. Back off and retry.
500internal_errorSomething failed on our side. Nothing was changed.