Scale and Franchise

TrustMetrics API

Versioned reads live at /api/v1. The API reads TrustMetrics' database. It does not call Google and it does not post replies. The machine-readable contract is /api/v1/openapi.json.

Authentication

Send Authorization: Bearer tm_ak_live_…. Owners and admins create keys. The full secret is shown once.

API keys belong to the organization, not to a person. Location managers do not get their own keys, and a key is not limited to one manager's locations.

events:write sends a completed job and lists locations on Growth and above. read:reviews, read:stats, and read:requests are the read API on Scale and Franchise. A key created before those scopes, or one that omits them, stays write-only. GET /api/v1/me accepts any live key.

Pagination

List endpoints take limit from 1 to 100 (default 20) and return next_cursor. Pass that value as cursor for the next page. A review that arrives after you read page one does not shift page two. until is exclusive.

Errors

Errors use { error: { code, message }, request_id }. The same id is in X-Request-Id.

  • 401 unauthorized — missing, unknown, or revoked key.
  • 403 insufficient_scope — the key does not include the scope for this path.
  • 403 not_entitled — the plan does not include this call. Read endpoints need Scale. Sending an event needs Growth.
  • 404 not_found — the read API is off, or Google review content is off. GET /reviews, GET /replies, and GET /ratings return 404 while that flag is off.
  • 422 invalid_query — a filter or cursor is not valid.
  • 429 rate_limited — the key or the organization is over its budget. Retry-After is in seconds.

Rate limits

Each key allows 600 requests a minute. Each organization allows 50,000 requests a day. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, plus the same three with a -Day suffix for the organization budget.

Review text is limited to rows still inside the 30-day storage window. Stats and the leaderboard are computed when you read them and are not saved. The leaderboard is ranked on one metric at a time. There is no combined score.

Successful reads send ETag. Repeat the call with If-None-Match to get 304. Responses use Cache-Control: private, no-store.

Examples

Locations

curl https://app.trustmetrics.io/api/v1/locations \
  -H "Authorization: Bearer tm_ak_live_..."

Reviews

curl "https://app.trustmetrics.io/api/v1/reviews?location_id=LOCATION_UUID&rating=5&replied=false&limit=20" \
  -H "Authorization: Bearer tm_ak_live_..."

Stats

curl "https://app.trustmetrics.io/api/v1/stats?period=last_month" \
  -H "Authorization: Bearer tm_ak_live_..."

Review requests

curl "https://app.trustmetrics.io/api/v1/review-requests?status=sent&limit=20" \
  -H "Authorization: Bearer tm_ak_live_..."

Leaderboard

curl "https://app.trustmetrics.io/api/v1/leaderboard?metric=velocity&period=30" \
  -H "Authorization: Bearer tm_ak_live_..."