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.dashboard

Read today's dashboard report — money in, and who is waiting
Read-onlyExpensive budget

REST

Shipping
POST /api/v1/reports/dashboard

MCP tool

Live
reports.dashboard

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

Operating contract

THE MORNING READ. What arrived today, what is outstanding, and — the half that actually needs somebody — which customers are waiting on a reply right now.

today.collected is money that ARRIVED today on the shop's own wall clock, not the server's. A shop in Calgary opening at eight is hours into UTC's tomorrow for part of the year, and a naive 24-hour window shows them yesterday afternoon's takings as today's.

today.unanswered_threads IS THE ONLY ACTIONABLE THING ON THIS RESPONSE. Each one is a customer who messaged more than two hours ago and has had no reply, with how long they have waited. Everything else here is a fact about the business; this is a list of people. Lead with it.

outstanding and open_quotes are LIFETIME figures, not today's. They are useful context and they read identically whether today went well or badly — do not present them as news.

imported_open_quotes is estimates carried in by a data import. They are real and searchable and they are NOT this week's pipeline: a file with no expiry column lands thousands of long-dead estimates, and folding them into the open-quote figure greets a shop with a pipeline nobody is chasing.

collected_trend is fourteen days of daily net collections, oldest first. A single number says where the shop is; this says which way it is going.

This mirrors /dashboard, which guards requireManager() — so unlike the rest of this domain it declares the admin key rather than reports.access.

One snapshot, measured at one instant (as_of), so nothing is truncated.

Who may call it

Permission
shop.manageThe caller must hold shop.manage 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.

Input

This capability takes no arguments.

Output

FieldTypeDescription
as_ofstring

—

today_keystring

—

currencystring

—

todayobject

—

today.collectednumber

—

today.payment_countnumber

—

today.unread_threadsnumber

—

today.unanswered_threadsobject[]

—

today.unanswered_threads[].conversation_idstring

—

today.unanswered_threads[].contactstring

—

today.unanswered_threads[].waiting_minutesnumber

—

open_quotesobject

—

open_quotes.countnumber

—

open_quotes.valuenumber

—

imported_open_quotesobject

—

imported_open_quotes.countnumber

—

imported_open_quotes.valuenumber

—

outstandingobject

—

outstanding.countnumber

—

outstanding.amountnumber

—

accepted_marginobject

—

accepted_margin.amountnumber

—

accepted_margin.avg_pctnumber | null

—

accepted_margin.countnumber

—

collected_trendnumber[]

—

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

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

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

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 shop.manage.
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.