openapi: 3.0.3
info:
  title: Trustpilot Business Units Reviews API
  description: Provides endpoints to retrieve company profile information, reviews, images, categories, and web links for specific business units on Trustpilot. Search for business units and access both public and private review data.
  version: 1.0.0
  contact:
    url: https://developers.trustpilot.com/
  termsOfService: https://www.trustpilot.com/legal/terms-and-conditions-for-businesses
servers:
- url: https://api.trustpilot.com
  description: Production
tags:
- name: Reviews
  description: Business unit review retrieval
paths:
  /v1/business-units/{businessUnitId}/reviews:
    get:
      operationId: getBusinessUnitReviews
      summary: Get Business Unit Reviews
      description: Fetch public reviews for a business unit with filtering and sorting options.
      tags:
      - Reviews
      security:
      - ApiKey: []
      parameters:
      - name: businessUnitId
        in: path
        required: true
        schema:
          type: string
      - name: stars
        in: query
        required: false
        schema:
          type: array
          items:
            type: integer
            enum:
            - 1
            - 2
            - 3
            - 4
            - 5
        description: Filter by star rating
      - name: language
        in: query
        required: false
        schema:
          type: string
        description: Filter reviews by language (ISO 639-1 code)
      - name: orderBy
        in: query
        required: false
        schema:
          type: string
          enum:
          - createdat.asc
          - createdat.desc
        description: Sort order for reviews
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: perPage
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Reviews returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewListResponse'
        '404':
          description: Business unit not found
  /v1/business-units/{businessUnitId}/all-reviews:
    get:
      operationId: getAllBusinessUnitReviews
      summary: Get All Business Unit Reviews
      description: Retrieve paginated public reviews using pageToken cursor-based pagination, supporting up to 100,000 reviews.
      tags:
      - Reviews
      security:
      - ApiKey: []
      parameters:
      - name: businessUnitId
        in: path
        required: true
        schema:
          type: string
      - name: pageToken
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor from previous response
      - name: perPage
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Reviews returned with pagination token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewListResponse'
  /v1/private/business-units/{businessUnitId}/reviews:
    get:
      operationId: getPrivateBusinessUnitReviews
      summary: Get Private Business Unit Reviews
      description: Access private reviews including customer contact information and order IDs.
      tags:
      - Reviews
      security:
      - OAuth2: []
      parameters:
      - name: businessUnitId
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
      - name: perPage
        in: query
        required: false
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: Private reviews returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateReviewListResponse'
  /v1/reviews/latest:
    get:
      operationId: getLatestReviews
      summary: Get Latest Reviews
      description: Gets the latest reviews written in a specific language.
      tags:
      - Reviews
      security:
      - ApiKey: []
      parameters:
      - name: count
        in: query
        required: true
        schema:
          type: integer
          maximum: 100
        description: Number of latest reviews to return
      - name: language
        in: query
        required: true
        schema:
          type: string
        description: ISO 639-1 language code
      - name: filterUsersWithoutImages
        in: query
        required: false
        schema:
          type: boolean
        description: Filter out reviews from users without profile images
      - name: locale
        in: query
        required: false
        schema:
          type: string
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Latest reviews returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  reviews:
                    type: array
                    items:
                      $ref: '#/components/schemas/Review_2'
  /v1/reviews/{reviewId}:
    get:
      operationId: getReview
      summary: Get Review
      description: Fetch public review information by review ID.
      tags:
      - Reviews
      security:
      - ApiKey: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Review details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Review_2'
        '404':
          description: Review not found
  /v1/reviews/{reviewId}/web-links:
    get:
      operationId: getReviewWebLinks
      summary: Get Review Web Links
      description: Retrieve public Trustpilot page URLs for a specific review.
      tags:
      - Reviews
      security:
      - ApiKey: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      - name: locale
        in: query
        required: true
        schema:
          type: string
        description: Locale for the web link
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Web links returned
  /v1/reviews/{reviewId}/likes:
    get:
      operationId: getReviewLikes
      summary: Get Review Likes
      description: Gets the list of consumers who have liked the review.
      tags:
      - Reviews
      security:
      - ApiKey: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Likes list returned
components:
  schemas:
    Review:
      type: object
      properties:
        id:
          type: string
          description: Unique review identifier
        stars:
          type: integer
          minimum: 1
          maximum: 5
          description: Star rating given by consumer
        title:
          type: string
          description: Review title
        text:
          type: string
          description: Review body text
        language:
          type: string
          description: Language code of the review
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        consumer:
          type: object
          properties:
            id:
              type: string
            displayName:
              type: string
        businessUnit:
          type: object
          properties:
            id:
              type: string
        status:
          type: string
          enum:
          - active
          - archived
        verificationLevel:
          type: string
          description: Verification level of the review
    ReviewListResponse:
      type: object
      properties:
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
        nextPageToken:
          type: string
        totalNumberOfReviews:
          type: integer
    PrivateReview:
      type: object
      allOf:
      - $ref: '#/components/schemas/Review'
      - type: object
        properties:
          consumer:
            type: object
            properties:
              email:
                type: string
              id:
                type: string
              displayName:
                type: string
          orderId:
            type: string
    Review_2:
      type: object
      properties:
        id:
          type: string
        stars:
          type: integer
          minimum: 1
          maximum: 5
        title:
          type: string
        text:
          type: string
        language:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        consumer:
          type: object
          properties:
            id:
              type: string
            displayName:
              type: string
        status:
          type: string
          enum:
          - active
          - archived
        verificationLevel:
          type: string
    PrivateReviewListResponse:
      type: object
      properties:
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/PrivateReview'
        totalNumberOfReviews:
          type: integer
  securitySchemes:
    ApiKey:
      type: apiKey
      in: query
      name: apikey
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://authenticate.trustpilot.com/oauth/connect/authorize
          tokenUrl: https://authenticate.trustpilot.com/oauth/token
          scopes:
            business.review.read: Read private review data