{"openapi":"3.1.0","info":{"title":"TrustRating Public API","version":"1.0.0","description":"Read access to public company profiles and their published reviews, plus write access to send review invitations. Authenticate with a Bearer API key (created in the business panel under API keys, or by an admin). Keys carry scopes — read endpoints require the `read` scope, mutations the `write` scope — and are rate limited per key (see the X-RateLimit-* response headers). Displaying review content retrieved from this API is subject to the Brand & Embed Guidelines (/legal/brand-guidelines): reviews must be shown unaltered, link back to the company's TrustRating profile, and carry a 'Reviews from TrustRating' attribution.","termsOfService":"https://trustrating.ai/legal/brand-guidelines"},"servers":[{"url":"https://trustrating.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key (prefixed `tr_`). Send as `Authorization: Bearer tr_...`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"Company":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"scoreOverall":{"type":"number","nullable":true},"reviewCount":{"type":"integer"},"verified":{"type":"boolean"},"domainVerified":{"type":"boolean"},"badgeTier":{"type":"string"}}},"Review":{"type":"object","properties":{"id":{"type":"string"},"rating":{"type":"integer","minimum":1,"maximum":5},"title":{"type":"string"},"body":{"type":"string"},"response":{"type":"string","nullable":true},"responseAt":{"type":"string","format":"date-time","nullable":true},"verifiedPurchase":{"type":"boolean"},"helpfulCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["EMAIL","SMS","BCC","LINK"]},"recipient":{"type":"string"},"recipientName":{"type":"string","nullable":true},"orderRef":{"type":"string","nullable":true},"status":{"type":"string","enum":["QUEUED","SENT","BOUNCED","OPENED","CLICKED","REVIEWED","EXPIRED","FAILED"]},"sentAt":{"type":"string","format":"date-time","nullable":true},"openedAt":{"type":"string","format":"date-time","nullable":true},"clickedAt":{"type":"string","format":"date-time","nullable":true},"reviewedAt":{"type":"string","format":"date-time","nullable":true},"expiresAt":{"type":"string","format":"date-time"},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"InvitationCreate":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Recipient email address."},"name":{"type":"string","description":"Recipient display name used in the email greeting."},"orderRef":{"type":"string","description":"Your order/transaction reference. When present, the resulting review is marked as a verified purchase."}}}}},"paths":{"/companies/{slug}":{"get":{"summary":"Get a company profile","operationId":"getCompany","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company profile","content":{"application/json":{"schema":{"type":"object","properties":{"company":{"$ref":"#/components/schemas/Company"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the read scope, or is scoped to a different company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/companies/{slug}/reviews":{"get":{"summary":"List a company's published reviews","operationId":"listCompanyReviews","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Pass the previous response's nextCursor to paginate."}],"responses":{"200":{"description":"Paginated reviews","content":{"application/json":{"schema":{"type":"object","properties":{"reviews":{"type":"array","items":{"$ref":"#/components/schemas/Review"}},"nextCursor":{"type":"string","nullable":true}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invitations":{"get":{"summary":"List your review invitations","description":"Lists the invitations of the company the API key is scoped to, newest first. Use this to poll delivery status (SENT → OPENED → CLICKED → REVIEWED). Requires a company-scoped key.","operationId":"listInvitations","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["QUEUED","SENT","BOUNCED","OPENED","CLICKED","REVIEWED","EXPIRED","FAILED"]},"description":"Only return invitations in this status."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Pass the previous response's nextCursor to paginate."}],"responses":{"200":{"description":"Paginated invitations","content":{"application/json":{"schema":{"type":"object","properties":{"invitations":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"nextCursor":{"type":"string","nullable":true}}}}}},"400":{"description":"Invalid status filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the read scope or is not company-scoped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a tracked review-invitation link","description":"Creates a per-recipient tracked review link for the company the API key is scoped to. The platform does NOT email the recipient — include the returned `url` in your own order-confirmation email or SMS. The link records opens/clicks and, when a review comes back with your `orderRef`, marks it as a verified purchase. Requires the `write` scope and a company-scoped key. Counts against the plan's monthly invitation quota. Recipients who unsubscribed (per-company or globally) are rejected with 422. Typical integration: call this from your order-confirmation webhook.","operationId":"createInvitation","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationCreate"}}}},"responses":{"201":{"description":"Invitation link created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["SENT"]},"url":{"type":"string","description":"Tracked review link — send this to the customer from your own email/SMS."},"expiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid body (e.g. malformed email)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the write scope, is not company-scoped, or invitations are blocked on the company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Recipient has unsubscribed from your invitations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly invitation quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}