REST API reference

Overview

The SalesThumb REST API lets you read shop data programmatically. Today it covers exactly three resources — customers, appointments, and invoices — each with a list endpoint and a get-by-ID endpoint (six endpoints total, all GET). All requests and responses are JSON, every row is scoped to the one shop your key belongs to, and the API is versioned (the current and only version is v1).

If you only need to react to events (e.g. a new invoice was paid), prefer webhooks — they require no polling, cover create/update/delete-shaped events, and are available on all plans today.

Authentication

Requests authenticate with an API key issued from Settings → API Keys, passed as a bearer token in the Authorization header — not as a query parameter, a custom header, or in the request body.

GET /api/v1/customers HTTP/1.1
Host: yourshop.salesthumb.com
Authorization: Bearer st_live_••••••••••••••••••••••••••••••••
Accept: application/jsonLanguage: http

A key resolves to exactly one shop — it can never read another shop's data, even if you manage multiple shops under the same account. Every request also needs the scope for the resource it's calling; see Scopes below.

Base URL & versioning

https://app.salesthumb.com/api/v1Language: text

There is no separate api.salesthumb.com host — every endpoint lives under /api/v1 on the same domain the app runs on. Your shop's own domain (e.g. yourshop.salesthumb.com) works identically to app.salesthumb.com: the API key in the Authorization header is what determines which shop's data a request can see, not the hostname you call it on.

All endpoints in this document are relative to that base. A breaking change, if one is ever needed, ships under a new version prefix (e.g. /api/v2) rather than changing v1 underneath you. Pin your code to named JSON fields, not positional assumptions, to stay forward-compatible with additive changes.

Pagination

All three list endpoints use cursor-based pagination. Pass limit (default 25, max 100 — anything higher is silently clamped) and cursor (the id of the last item from the previous page) to page forward.

GET /api/v1/customers?limit=25&cursor=3fa85f64-5717-4562-b3fc-2c963f66afa6Language: http

Every list response is a flat object with two fields:

{
  "items": [ /* array of objects */ ],
  "nextCursor": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}Language: json

nextCursor is null on the last page — that's the only end-of-collection signal; there is no has_more flag or total count. GET /api/v1/appointments also accepts optional startDate and endDate query params (ISO date strings, inclusive) filtering on the appointment's start time.

Rate limiting

The API allows 300 requests per minute per API key, in a rolling 60-second window. The limit is bucketed per key, not per shop or per IP — two keys on the same shop each get their own 300/min budget.

// Response 429
{
  "error": "Rate limit exceeded"
}Language: json

When you exceed the limit the API returns HTTP 429 with that body. No Retry-After or X-RateLimit-* headers are sent on any response today — implement your own backoff (waiting roughly a minute is a safe default) rather than reading response headers for a retry hint.

Scopes

Every key carries one or more scopes, chosen when the key is created (Settings → API Keys offers Read-only, Read + write, and Admin presets). A request without the scope its endpoint requires gets a 403 that names the missing scope:

// Response 403
{
  "error": "This API key does not have the \"read:customers\" scope"
}Language: json

Error codes

Every error response is a flat JSON object with a single error string, matching the HTTP status:

{
  "error": "Missing or invalid API key"
}Language: json

Customers

A Customer represents a person or business the shop has scheduled, quoted, or invoiced. Requires the read:customers scope.

// Response 200
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "firstName": "Jordan",
      "lastName": "Rivera",
      "email": "jordan@example.com",
      "phone": "+15125550182",
      "companyName": null,
      "isFleet": false,
      "address1": null,
      "address2": null,
      "city": null,
      "state": null,
      "zipCode": null,
      "tags": [],
      "marketingOptIn": true,
      "createdAt": "2026-03-15T10:22:00.000Z",
      "updatedAt": "2026-04-01T08:00:00.000Z"
    }
  ],
  "nextCursor": null
}Language: json

// Response 200
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "firstName": "Jordan",
  "lastName": "Rivera",
  "email": "jordan@example.com",
  "phone": "+15125550182",
  "companyName": null,
  "isFleet": false,
  "address1": null,
  "address2": null,
  "city": null,
  "state": null,
  "zipCode": null,
  "tags": [],
  "marketingOptIn": true,
  "createdAt": "2026-03-15T10:22:00.000Z",
  "updatedAt": "2026-04-01T08:00:00.000Z"
}

// Response 404
{ "error": "Customer not found" }Language: json

Appointments

An Appointment is a scheduled service visit. status is one of PENDING_DEPOSIT, SCHEDULED, CONFIRMED, CHECKED_IN, IN_PROGRESS, READY, COMPLETED, NO_SHOW, or CANCELED. Requires the read:appointments scope.

GET /api/v1/appointments?startDate=2026-06-01&endDate=2026-06-30&limit=10Language: http

// Response 404
{ "error": "Appointment not found" }Language: json

Invoices

An Invoice represents money owed by a customer. status is one of DRAFT, SENT, PARTIAL, PAID, VOID, or REFUNDED. Requires the read:invoices scope.

// Response 200
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "5b1e4a2c-8f0d-4a3e-9c7b-1a2b3c4d5e6f",
  "vehicleId": null,
  "number": "INV-1042",
  "status": "SENT",
  "subtotalCents": 82900,
  "taxCents": 5040,
  "discountCents": 0,
  "feesCents": 0,
  "totalCents": 87940,
  "depositAppliedCents": 0,
  "balanceCents": 87940,
  "dueDate": "2026-06-10",
  "notes": null,
  "sentAt": "2026-05-25T14:20:00.000Z",
  "paidAt": null,
  "createdAt": "2026-05-25T14:20:00.000Z",
  "updatedAt": "2026-05-25T14:20:00.000Z"
}Language: json