API documentation

Getting started

The TrustRating API is a JSON REST API served from https://trustrating.ai/api/v1. It gives you programmatic access to the same public data shown on company profiles, plus invitation tooling for collecting verified reviews from your own customers.

1. Claim your company on TrustRating (if you haven't already) and open the business panel.
2. Create an API key under Business panel → API keys. Pick the permissions the key needs: Read for fetching data, Write for creating invitations.
3. Call the API with the key in the Authorization header:

curl https://trustrating.ai/api/v1/companies/your-company-slug \
  -H "Authorization: Bearer tr_your_api_key"

Keys created in the business panel are scoped to your company: they can read your own profile and reviews and manage your own invitations, but nothing belonging to other companies.

Authentication

Every request must carry an API key (prefixed tr_) as a Bearer token. Keys are shown once at creation — store them like passwords and rotate them from the business panel if leaked.

Authorization: Bearer tr_your_api_key

Requests without a valid key return 401; a valid key missing the required scope returns 403. API access is also a plan capability — if your current plan doesn't include the API, requests return 403 with an upgrade hint.

Keep keys server-side. API keys are secrets: call the API from your backend, never from browser JavaScript or mobile apps where the key is visible to anyone who opens dev tools. If a key leaks, revoke it in the business panel and create a new one — revocation is immediate.

Rate limits

Each key has a per-minute request budget (chosen when the key is created). Every response reports the current window in headers; exceeding the budget returns 429 — back off until the reset time.

Two budgets apply: the per-minute rate limit above (429 with a Retry-After header — back off and retry) and your plan's monthly request quota, reported in the X-Quota-* headers (429 without Retry-After — it resets with the billing period, not a clock window).

Get a company profile

Returns the public profile of a company: name, domain, description, verification state, review count and the public score — both on the internal 0–100 scale (scoreOverall) and as the 0–5 star rating shown on the site (stars).

curl https://trustrating.ai/api/v1/companies/example-company \
  -H "Authorization: Bearer tr_your_api_key"

{
  "company": {
    "id": "cmp_9f2k1",
    "slug": "example-company",
    "name": "Example Company Inc.",
    "domain": "example.com",
    "description": "Industrial-grade everything.",
    "logo": "https://trustrating.ai/media/example-logo.webp",
    "founded": 2004,
    "headquarters": "Berlin, Germany",
    "category": { "slug": "software", "name": "Software" },
    "scoreOverall": 86,
    "stars": 4.3,
    "reviewCount": 412,
    "verified": true,
    "domainVerified": true,
    "badgeTier": "GOLD",
    "createdAt": "2025-02-11T08:44:00.000Z",
    "updatedAt": "2026-07-20T16:02:31.000Z"
  }
}

List a company's published reviews

Returns published reviews, newest first, with cursor pagination. Each review includes the author's public display name and the company's reply when one exists.

curl "https://trustrating.ai/api/v1/companies/example-company/reviews?limit=2" \
  -H "Authorization: Bearer tr_your_api_key"

{
  "reviews": [
    {
      "id": "rev_7d31x",
      "rating": 5,
      "title": "Delivery was faster than promised",
      "body": "Ordered on Monday, arrived Wednesday. Support answered in minutes.",
      "response": "Thank you! We just rolled out same-week delivery.",
      "responseAt": "2026-07-18T10:12:00.000Z",
      "verifiedPurchase": true,
      "helpfulCount": 12,
      "createdAt": "2026-07-17T19:40:11.000Z",
      "user": { "name": "Maria K.", "username": "maria-k" }
    }
  ],
  "nextCursor": "rev_7d31x",
  "attribution": {
    "required": true,
    "text": "Reviews from TrustRating",
    "policy": "https://trustrating.ai/legal/brand-guidelines"
  }
}

nextCursor is null on the last page. Note the attribution block in every payload — see Attribution rules before displaying reviews outside TrustRating.

Review invitations

Invitations are per-customer tracked review links. TrustRating never emails your customers — you create a link and include it in your own order-confirmation email or SMS. The link records opens and clicks, and when the customer leaves a review it is tied back to your orderRef and marked as a verified purchase. Both operations require a company-scoped key; creating links needs the write scope and counts against your plan's monthly invitation quota.

Create a tracked link

curl -X POST https://trustrating.ai/api/v1/invitations \
  -H "Authorization: Bearer tr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "name": "Maria",
    "orderRef": "ORDER-10422"
  }'

{
  "id": "inv_2h8p4",
  "status": "SENT",
  "url": "https://trustrating.ai/r/inv_2h8p4",
  "expiresAt": "2026-08-22T10:00:00.000Z"
}

Typical integration: call this from your order-confirmation webhook, then merge url into the email you already send. Recipients who unsubscribed from your invitations are rejected with 422.

Poll delivery status

Lists your invitations, newest first, with the same limit / cursor pagination as reviews. Filter with ?status= — one of QUEUED, SENT, BOUNCED, OPENED, CLICKED, REVIEWED, EXPIRED, FAILED.

curl "https://trustrating.ai/api/v1/invitations?status=REVIEWED&limit=20" \
  -H "Authorization: Bearer tr_your_api_key"

Errors

Errors use conventional HTTP status codes and always carry a JSON body with a single error message:

{ "error": "Rate limit exceeded" }

Webhooks

Instead of polling, subscribe to events under Business panel → Webhooks. We POST a JSON payload to your URL whenever a subscribed event fires; failed deliveries are retried with exponential backoff (1 min → 5 min → 25 min → ~2 h → ~10 h).

POST https://your-server.example/webhooks/trustrating
Content-Type: application/json
X-TrustRating-Signature: 3f1c2a… (HMAC-SHA256 of the raw body)
X-TrustRating-Webhook-Id: whk_8s5k2

{
  "event": "REVIEW_PUBLISHED",
  "companyId": "cmp_9f2k1",
  "ts": 1784102530000,
  "data": { "reviewId": "rev_7d31x", "rating": 5 }
}

Every delivery is signed with your webhook's secret (shown when you create the subscription). Verify before trusting the payload:

import crypto from "node:crypto";

function isFromTrustRating(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return (
    signatureHeader.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))
  );
}

Compute the HMAC over the raw request body (before JSON parsing) — re-serialising the parsed object can change key order and break the comparison.

Attribution rules

Review content retrieved from this API may be displayed on your own site subject to the Brand & Embed Guidelines:

• Show reviews unaltered — no edits, no cherry-picked truncation that changes meaning.
• Link back to the company's TrustRating profile.
• Carry a visible “Reviews from TrustRating” attribution (the exact string is included in every reviews payload).

Prefer not to build it yourself? The business panel's Widgets section generates embeddable review and TrustScore widgets that already comply.