# Trustpilot (/docs/trustpilot)

Find a company on Trustpilot and pull its customer reviews behind the unified review schema

Trustpilot is where people write about companies: shipping, refunds, support, whether the thing arrived. These two endpoints find a business and return its reviews in the same canonical `Review` shape as Amazon, Google Shopping and Tripadvisor, so one parser reads them all.

Base URL: `/v1/trustpilot/...`

It is a two-step flow, and the joining key is the business's Trustpilot **domain**.

  Pass a company name to `business-search`, never a bare domain. It matches
  business names, so `nike` finds Nike and `nike.com` returns nothing at all.
  The domain is the *output* of that call, not an input to it.

## Quickstart

### Find the company

Read the Trustpilot domain off the result.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/trustpilot/business-search?query=monzo" \
  -H "x-api-key: YOUR_API_KEY"
```

### Pull its reviews using that domain

Already know the domain? Skip step 1. `domain` is just the company's site, so `monzo.com` works without a lookup in most cases. Search is there for when the Trustpilot listing does not match the obvious domain.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/trustpilot/reviews?domain=monzo.com&depth=100&sort=recency" \
  -H "x-api-key: YOUR_API_KEY"
```

## Companies

| Endpoint                             | Credits | What it returns                                                                                                | Key parameters              |
| ------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `GET /v1/trustpilot/business-search` | 1       | Matching businesses with company name, Trustpilot domain, own website, review-page URL, and total review count | `query` (required), `depth` |

`depth` is the result count: default 20, in multiples of 10, max 140.

## Reviews

| Endpoint                     | Credits | What it returns                                                                                     | Key parameters                       |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `GET /v1/trustpilot/reviews` | 5       | Star rating, title, full text, verified status, language, reviewer, any company reply, publish date | `domain` (required), `depth`, `sort`, `label`, `judgments` |

`depth` is default 20, in multiples of 20, max 200. `sort` is `recency` (newest first, the default) or `relevance`.

## All endpoints

## Platform notes

**200 reviews is the whole ceiling.** `depth` caps at 200 and there is no pagination beyond it: no cursor, no page parameter, nothing deeper. What you get is the 200 most recent or most relevant, per `sort`. Plan longitudinal tracking as repeated `sort=recency` pulls over time rather than one deep crawl.

**Reviews arrive in many languages.** Trustpilot is heavily used outside English-speaking markets and the endpoint returns whatever was written. Every review carries a `language`, so filter client-side rather than expecting an English-only feed.

**First calls are slow, then cached.** A cold call takes roughly 15 to 45 seconds because the upstream settles a task before answering; repeats serve from cache. Set client timeouts accordingly. A business with no Trustpilot reviews returns `404`, refunded automatically.

**Trustpilot reviews companies, not products.** This is the distinction that decides whether Trustpilot is the right source at all. A Trustpilot review is about the seller: delivery, returns, billing, the support experience. It will not tell you whether a specific SKU is any good.

For product-level opinion use [Amazon](/docs/amazon.md) or [Google Shopping](/docs/google_shopping.md) reviews instead, or `GET /v1/prism/product-reviews` (30 credits), which folds Amazon, Google Shopping and Trustpilot into one cross-marketplace rating with themed pros and cons. For a whole company across review sites, app stores, Google Business and web sentiment, `GET /v1/prism/reputation` (30 credits) is the one call that covers it, and Trustpilot is one of its legs.

## Labels

`/v1/trustpilot/reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

## Next steps

- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [Pagination](/docs/pagination.md): Why depth replaces the cursor on both endpoints here.
- [API reference](/docs/api-reference.md): Every Trustpilot parameter and response field.
- [Tripadvisor](/docs/tripadvisor.md): Traveler reviews for places, in the same review shape.
- [Prism](/docs/prism.md): Cross-source reputation and product reviews in one call.