openapi: 3.0.3
info:
  title: Trustpilot Business Units Review Management 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: Review Management
  description: Private review management operations
paths:
  /v1/private/reviews/{reviewId}:
    get:
      operationId: getPrivateReview
      summary: Get Private Review
      description: Retrieve a review with private details including status and consumer information.
      tags:
      - Review Management
      security:
      - OAuth2: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Private review returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrivateReview'
  /v1/private/reviews/{reviewId}/reply:
    post:
      operationId: createReviewReply
      summary: Create Review Reply
      description: Post a company reply to a service review.
      tags:
      - Review Management
      security:
      - OAuth2: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: Reply message text
                authorBusinessUserId:
                  type: string
                  description: Business user ID of the reply author
      responses:
        '201':
          description: Reply posted successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
    delete:
      operationId: deleteReviewReply
      summary: Delete Review Reply
      description: Remove a company response from a review.
      tags:
      - Review Management
      security:
      - OAuth2: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Reply deleted successfully
  /v1/private/reviews/{reviewId}/tags:
    get:
      operationId: getReviewTags
      summary: Get Review Tags
      description: Retrieve all tags assigned to a service review.
      tags:
      - Review Management
      security:
      - OAuth2: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Tags returned
    post:
      operationId: setReviewTags
      summary: Set Review Tags
      description: Set the tags of a service review, replacing existing tags.
      tags:
      - Review Management
      security:
      - OAuth2: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      group:
                        type: string
                      value:
                        type: string
      responses:
        '200':
          description: Tags set successfully
    put:
      operationId: addReviewTags
      summary: Add Review Tags
      description: Add tags to a service review.
      tags:
      - Review Management
      security:
      - OAuth2: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  items:
                    type: object
                    properties:
                      group:
                        type: string
                      value:
                        type: string
      responses:
        '200':
          description: Tags added successfully
    delete:
      operationId: deleteReviewTag
      summary: Delete Review Tag
      description: Remove a specific tag from a review.
      tags:
      - Review Management
      security:
      - OAuth2: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      - name: group
        in: query
        required: true
        schema:
          type: string
      - name: value
        in: query
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Tag deleted
  /v1/private/reviews/{reviewId}/find-reviewer:
    post:
      operationId: findReviewer
      summary: Find Reviewer
      description: Initiate a reviewer identification request for a review.
      tags:
      - Review Management
      security:
      - OAuth2: []
      parameters:
      - name: reviewId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                skipNotificationEmailToBusinessUser:
                  type: boolean
      responses:
        '200':
          description: Find reviewer request initiated
components:
  schemas:
    Review:
      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
    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
  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