{ "openapi": "3.1.0", "info": { "title": "Trustpilot Reviews API", "version": "1.0.0", "description": "Public Trustpilot company profiles, TrustScores, rating distributions and reviews exposed through FetchLayer as structured JSON." }, "servers": [ { "url": "https://api.fetchlayer.dev/trustpilot" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search-companies": { "post": { "operationId": "search-companies", "tags": [ "Companies" ], "summary": "Find companies by name", "description": "Look up companies on Trustpilot by name, brand or keyword. Each match comes back with its domain, TrustScore, star rating, review count, categories, location and published contact details. The domain on a result is the identifier every other Trustpilot endpoint takes, so this is the route that turns a brand name into something you can fetch a profile or reviews for.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Company name, brand, or keyword to look up." }, "limit": { "type": "number", "description": "Maximum companies returned (max 1000), or -1 for everything available.", "example": "10" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "meal kit delivery", "limit": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocked": { "type": "boolean", "description": "Always false on a successful response." }, "requestedUrl": { "type": "string", "description": "The Trustpilot URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "transport": { "type": "string", "description": "The upstream source this data came from. Always \"trustpilot\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a list that hit a cap, a filter that narrowed it, a walk that stopped early. Read it: it is where a truncated or incomplete answer announces itself." }, "resultType": { "type": "string", "description": "Which shape this response is: company-search, company-profile, company-reviews, or review-detail." }, "query": { "type": "string", "description": "The search term this response answers." }, "companies": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "domain": { "type": "string", "description": "The company’s identifier on Trustpilot — the handle for company-profile and company-reviews." }, "companyId": { "type": "string", "description": "Trustpilot’s internal company id." }, "displayName": { "type": "string", "description": "Company name as shown on the profile." }, "profileUrl": { "type": "string", "description": "Public Trustpilot profile URL." }, "trustScore": { "type": "number", "description": "TrustScore from 0 to 5, to one decimal place." }, "stars": { "type": "number", "description": "The score rounded to the nearest half star." }, "reviewCount": { "type": "number", "description": "Total reviews the company has." }, "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Categories the company is listed under, with which one is primary." }, "location": { "type": "object", "additionalProperties": true, "description": "Address, city, zip code and country, where published." }, "contact": { "type": "object", "additionalProperties": true, "description": "Website, email and phone, where published." } } }, "description": "The matching companies." }, "companyCount": { "type": "number", "description": "Number of companies in this response." }, "totalMatchCount": { "type": "number", "description": "Matches Trustpilot reports across every page. Capped upstream on broad queries." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages this request asked for. Lower than pagesScraped means the walk stopped early — notes says why." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when there is nothing further to collect." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "company-search", "query": "meal kit delivery", "companyCount": 10, "totalMatchCount": 184, "hasNextPage": true, "notes": [], "companies": [ { "domain": "hellofresh.com", "displayName": "HelloFresh", "trustScore": 4.2, "stars": 4, "reviewCount": 97539, "profileUrl": "https://www.trustpilot.com/review/hellofresh.com" } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/company-profile": { "post": { "operationId": "company-profile", "tags": [ "Companies" ], "summary": "Get a company’s rating summary", "description": "Read a company’s Trustpilot profile in one call: TrustScore, total review count, reviews in the last twelve months, and the full one-to-five star distribution. It also returns the category breadcrumb, location and contact details, whether the company has claimed the profile and is still collecting reviews, how often and how fast it replies to negative reviews, any consumer alert Trustpilot has published against it, and the review count per language — which is what tells you how to split a reviews pull that would otherwise hit the 200-review ceiling.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "string", "description": "Company domain (for example hellofresh.com), or a Trustpilot company URL." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "company" ] }, "examples": { "default": { "value": { "company": "hellofresh.com" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocked": { "type": "boolean", "description": "Always false on a successful response." }, "requestedUrl": { "type": "string", "description": "The Trustpilot URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "transport": { "type": "string", "description": "The upstream source this data came from. Always \"trustpilot\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a list that hit a cap, a filter that narrowed it, a walk that stopped early. Read it: it is where a truncated or incomplete answer announces itself." }, "resultType": { "type": "string", "description": "Which shape this response is: company-search, company-profile, company-reviews, or review-detail." }, "profile": { "type": "object", "additionalProperties": true, "description": "The company’s full profile record.", "properties": { "domain": { "type": "string", "description": "The company’s identifier on Trustpilot." }, "displayName": { "type": "string", "description": "Company name as shown on the profile." }, "trustScore": { "type": "number", "description": "TrustScore from 0 to 5, to one decimal place." }, "reviewCount": { "type": "number", "description": "Total reviews the company has." }, "reviewCountLast12Months": { "type": "number", "description": "Reviews published in the last twelve months." }, "ratingDistribution": { "type": "object", "additionalProperties": true, "description": "How many reviews sit at each star rating. The five buckets sum to total — use them to plan a per-rating partition of a reviews pull." }, "reviewLanguages": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Review count per language, with its two-letter code. The other axis to partition a reviews pull on." }, "categories": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Categories the company is listed under, with which one is primary." }, "categoryBreadcrumb": { "type": "array", "items": { "type": "string" }, "description": "The company’s position in the category tree, broadest level first." }, "standing": { "type": "object", "additionalProperties": true, "description": "Whether the profile is claimed, closed, merged or still collecting reviews, plus verification flags.", "properties": { "consumerAlerts": { "type": "array", "items": { "type": "string" }, "description": "Warnings Trustpilot has published about this company." }, "replyPercentage": { "type": "number", "description": "Share of negative reviews the company replied to, 0-100." }, "averageDaysToReply": { "type": "number", "description": "How long the company typically takes to answer a negative review." } } }, "location": { "type": "object", "additionalProperties": true, "description": "Address, city, zip code and country, where published." }, "contact": { "type": "object", "additionalProperties": true, "description": "Website, email and phone, where published." }, "locationsCount": { "type": "number", "description": "How many locations the company lists on Trustpilot." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "company-profile", "notes": [], "profile": { "domain": "hellofresh.com", "displayName": "HelloFresh", "trustScore": 4.2, "reviewCount": 97539, "reviewCountLast12Months": 21408, "ratingDistribution": { "total": 97539, "oneStar": 9211, "twoStar": 3044, "threeStar": 4102, "fourStar": 15880, "fiveStar": 65302 }, "standing": { "isClaimed": true, "isCollectingReviews": true, "replyPercentage": 92.4, "consumerAlerts": [] }, "reviewLanguages": [ { "isoCode": "en", "displayName": "English", "reviewCount": 74120 } ] } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/company-reviews": { "post": { "operationId": "company-reviews", "tags": [ "Reviews" ], "summary": "Get a company’s reviews", "description": "Return a company’s public Trustpilot reviews — rating, title, text, language, date of experience, reviewer, verification status, and the company’s reply where it answered. Filter by star rating, review language, date window, verified reviewers, a keyword, or replied-to only, and sort by recency or relevance. Trustpilot serves at most 200 reviews per filter combination to an anonymous reader, whatever the company’s total: a company with 97,539 reviews still returns 200 and nothing on the page explains why. The way past it is to partition — one request per star rating, one per language, or one per date window — and merge the results. When the request hits that ceiling the response says so in notes, so read notes rather than assuming a 200-review answer is complete.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "type": "string", "description": "Company domain (for example hellofresh.com), or a Trustpilot company URL." }, "stars": { "type": "array", "items": { "type": "number" }, "description": "Only reviews with these star ratings, for example [1, 2]. The primary axis for partitioning past the 200-review ceiling." }, "language": { "type": "string", "description": "Two-letter review language code, or \"all\" for every language.", "example": "all" }, "dateWindow": { "type": "string", "description": "all, last30days, last3months, or last6months.", "example": "all" }, "sort": { "type": "string", "description": "recency (newest first) or relevance.", "example": "recency" }, "verifiedOnly": { "type": "boolean", "description": "Only reviews whose reviewer was verified by Trustpilot." }, "repliedOnly": { "type": "boolean", "description": "Only reviews the company has replied to." }, "search": { "type": "string", "description": "Only reviews whose text matches this keyword (max 200 characters)." }, "limit": { "type": "number", "description": "Maximum reviews returned (max 200), or -1 for everything available.", "example": "20" }, "pages": { "type": "number", "description": "Pages of reviews to collect in one request (max 10), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "company" ] }, "examples": { "default": { "value": { "company": "hellofresh.com", "stars": [ 1, 2 ], "language": "en", "dateWindow": "last3months", "limit": 200, "pages": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocked": { "type": "boolean", "description": "Always false on a successful response." }, "requestedUrl": { "type": "string", "description": "The Trustpilot URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "transport": { "type": "string", "description": "The upstream source this data came from. Always \"trustpilot\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a list that hit a cap, a filter that narrowed it, a walk that stopped early. Read it: it is where a truncated or incomplete answer announces itself." }, "resultType": { "type": "string", "description": "Which shape this response is: company-search, company-profile, company-reviews, or review-detail." }, "domain": { "type": "string", "description": "The resolved company domain." }, "companyId": { "type": "string", "description": "Trustpilot’s internal company id." }, "displayName": { "type": "string", "description": "Company name as shown on the profile." }, "trustScore": { "type": "number", "description": "The company’s TrustScore at the time of the request." }, "totalReviewCount": { "type": "number", "description": "Every review the company has, before this request’s filters." }, "filteredReviewCount": { "type": "number", "description": "Reviews matching this request’s filters. Compare it with reviewCount to see how much of the filtered set the 200-review ceiling left behind." }, "filters": { "type": "object", "additionalProperties": true, "description": "The filters this request actually ran with, after defaults were applied." }, "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "reviewId": { "type": "string", "description": "Review id — the handle for the review endpoint." }, "reviewUrl": { "type": "string", "description": "Public Trustpilot permalink for this review." }, "rating": { "type": "number", "description": "Star rating, 1 to 5." }, "title": { "type": "string", "description": "Review headline." }, "text": { "type": "string", "description": "Review body." }, "language": { "type": "string", "description": "Two-letter code of the review text’s language." }, "experiencedAt": { "type": "string", "description": "When the reviewer says the experience happened." }, "publishedAt": { "type": "string", "description": "When the review was published." }, "likes": { "type": "number", "description": "\"Useful\" votes from other readers." }, "author": { "type": "object", "additionalProperties": true, "description": "Reviewer display name, country, total reviews written, reviews written about this company, and whether they are verified." }, "verification": { "type": "object", "additionalProperties": true, "description": "How the review was collected and whether Trustpilot verified it — for example \"invited\" or \"not-verified\"." }, "reply": { "type": "object", "additionalProperties": true, "description": "The company’s published answer, with its message and dates. Null when the company has not replied." }, "isFiltered": { "type": "boolean", "description": "True when Trustpilot is currently hiding this review from the company’s list." }, "productNames": { "type": "array", "items": { "type": "string" }, "description": "Products the reviewer rated alongside the company, where any." } } }, "description": "The matching reviews." }, "reviewCount": { "type": "number", "description": "Number of reviews in this response." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages this request asked for. Lower than pagesScraped means the walk stopped early — notes says why." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when there is nothing further to collect." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "company-reviews", "domain": "hellofresh.com", "displayName": "HelloFresh", "trustScore": 4.2, "totalReviewCount": 97539, "filteredReviewCount": 1842, "filters": { "stars": [ 1, 2 ], "language": "en", "dateWindow": "last3months", "sort": "recency", "verifiedOnly": false, "repliedOnly": false, "search": null }, "reviewCount": 200, "pagesScraped": 10, "hasNextPage": false, "notes": [ "Trustpilot served the maximum 200 reviews for this filter combination. Narrow the filters (star rating, language, or date window) and run several requests to read more." ], "reviews": [ { "reviewId": "a1b2c3d4e5f60718293a4b5c", "rating": 1, "title": "Box never arrived", "text": "Ordered for Tuesday, nothing turned up…", "language": "en", "experiencedAt": "2026-08-30", "reply": { "message": "We are sorry to hear this…", "publishedDate": "2026-09-01" } } ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/review": { "post": { "operationId": "review", "tags": [ "Reviews" ], "summary": "Get one review by id", "description": "Read a single Trustpilot review in full from its id or its Trustpilot link: rating, title, complete text, date of experience, publication and update dates, the reviewer, how the review was verified, and the company’s reply. It also identifies the company the review is about. This is the one route that reaches a review the listing cannot: because company-reviews stops at 200 per filter combination, an older review that falls past that depth is unreachable by listing but still fetchable here by id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": "string", "description": "Review id, or a Trustpilot review URL containing one." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "review" ] }, "examples": { "default": { "value": { "review": "https://www.trustpilot.com/reviews/a1b2c3d4e5f60718293a4b5c" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "blocked": { "type": "boolean", "description": "Always false on a successful response." }, "requestedUrl": { "type": "string", "description": "The Trustpilot URL this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO 8601 timestamp of when the data was collected." }, "transport": { "type": "string", "description": "The upstream source this data came from. Always \"trustpilot\"." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a list that hit a cap, a filter that narrowed it, a walk that stopped early. Read it: it is where a truncated or incomplete answer announces itself." }, "resultType": { "type": "string", "description": "Which shape this response is: company-search, company-profile, company-reviews, or review-detail." }, "reviewId": { "type": "string", "description": "The resolved review id." }, "review": { "type": "object", "additionalProperties": true, "description": "The full review record, in the same shape company-reviews returns.", "properties": { "rating": { "type": "number", "description": "Star rating, 1 to 5." }, "title": { "type": "string", "description": "Review headline." }, "text": { "type": "string", "description": "Review body." }, "author": { "type": "object", "additionalProperties": true, "description": "Reviewer display name, country, review counts and verification flag." }, "verification": { "type": "object", "additionalProperties": true, "description": "How the review was collected and whether Trustpilot verified it." }, "reply": { "type": "object", "additionalProperties": true, "description": "The company’s published answer, or null." } } }, "company": { "type": "object", "additionalProperties": true, "description": "The company the review is about: companyId, domain, displayName and profileUrl." } }, "additionalProperties": false }, "examples": { "default": { "value": { "resultType": "review-detail", "reviewId": "a1b2c3d4e5f60718293a4b5c", "notes": [], "review": { "rating": 1, "title": "Box never arrived", "text": "Ordered for Tuesday, nothing turned up…", "language": "en", "publishedAt": "2026-08-31T09:14:02Z", "author": { "displayName": "Jordan P.", "countryCode": "GB", "reviewCount": 7 } }, "company": { "domain": "hellofresh.com", "displayName": "HelloFresh", "profileUrl": "https://www.trustpilot.com/review/hellofresh.com" } } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse a Trustpilot URL", "description": "Turn any Trustpilot URL into the structured input it encodes — whether it points at a company, a single review or a search, plus the company domain, review id, or the star, language, date window, sort, verified, replied and keyword filters carried in its query string. Hand it a URL a colleague pasted and it comes back as the exact request body company-reviews takes. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any Trustpilot URL, to be parsed into structured input." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" }, "timeoutMs": { "type": "number", "description": "Per-request time limit in milliseconds (max 600000)." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://www.trustpilot.com/review/hellofresh.com?stars=1&stars=2&languages=en&date=last3months" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the URL points at: company, review, or search." }, "url": { "type": "string", "description": "The URL that was parsed." }, "domain": { "type": "string", "description": "Present when kind is company — pass it to company-profile or company-reviews." }, "reviewId": { "type": "string", "description": "Present when kind is review — pass it to the review endpoint." }, "query": { "type": "string", "description": "Present when kind is search — pass it to search-companies." }, "stars": { "type": "array", "items": { "type": "number" }, "description": "Star filter carried in the URL." }, "language": { "type": "string", "description": "Language filter carried in the URL." }, "dateWindow": { "type": "string", "description": "Date window carried in the URL." }, "sort": { "type": "string", "description": "Sort order carried in the URL." }, "verifiedOnly": { "type": "boolean", "description": "Verified-reviewer filter carried in the URL." }, "repliedOnly": { "type": "boolean", "description": "Replied-to filter carried in the URL." }, "search": { "type": "string", "description": "Keyword filter carried in the URL." }, "page": { "type": "number", "description": "Page number carried in the URL." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "company", "domain": "hellofresh.com", "reviewId": null, "query": null, "stars": [ 1, 2 ], "language": "en", "dateWindow": "last3months", "sort": null, "verifiedOnly": null, "repliedOnly": null, "search": null, "page": null } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }