openapi: 3.0.3
info:
  title: Trustpilot Business Units 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: Business Units
  description: Business unit profile and review operations
paths:
  /v1/business-units/search:
    get:
      operationId: searchBusinessUnits
      summary: Search Business Units
      description: Search for business units on Trustpilot, even if you only know part of the name.
      tags:
      - Business Units
      security:
      - ApiKey: []
      parameters:
      - name: name
        in: query
        required: false
        schema:
          type: string
        description: Business name or partial name to search for
      - name: country
        in: query
        required: false
        schema:
          type: string
        description: Filter results by ISO 3166-1 alpha-2 country code
      - name: page
        in: query
        required: false
        schema:
          type: integer
          default: 1
        description: Page number for pagination
      - name: perPage
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
        description: Number of results per page
      - name: apikey
        in: query
        required: true
        schema:
          type: string
        description: Your Trustpilot API key
      responses:
        '200':
          description: Search results returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessUnitSearchResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /v1/business-units/{businessUnitId}/profileinfo:
    get:
      operationId: getBusinessUnitProfile
      summary: Get Business Unit Profile
      description: Retrieve company profile information including contact details and social media links.
      tags:
      - Business Units
      security:
      - ApiKey: []
      parameters:
      - name: businessUnitId
        in: path
        required: true
        schema:
          type: string
        description: Unique Trustpilot business unit identifier
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Business unit profile returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessUnitProfile'
        '404':
          description: Business unit not found
  /v1/business-units/{businessUnitId}/categories:
    get:
      operationId: getBusinessUnitCategories
      summary: Get Business Unit Categories
      description: List categories associated with a business unit.
      tags:
      - Business Units
      security:
      - ApiKey: []
      parameters:
      - name: businessUnitId
        in: path
        required: true
        schema:
          type: string
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Categories returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryListResponse'
  /v1/business-units/{businessUnitId}/web-links:
    get:
      operationId: getBusinessUnitWebLinks
      summary: Get Business Unit Web Links
      description: Obtain links to the business unit's public profile page on Trustpilot.
      tags:
      - Business Units
      security:
      - ApiKey: []
      parameters:
      - name: businessUnitId
        in: path
        required: true
        schema:
          type: string
      - name: locale
        in: query
        required: false
        schema:
          type: string
        description: Locale code for localized URLs
      - name: apikey
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Web links returned
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    BusinessUnitSummary:
      type: object
      properties:
        id:
          type: string
          description: Trustpilot business unit ID
        displayName:
          type: string
        name:
          type: string
        websiteUrl:
          type: string
        countryCode:
          type: string
        trustScore:
          type: number
          format: double
        stars:
          type: number
          format: double
        numberOfReviews:
          type: object
          properties:
            total:
              type: integer
    CategoryListResponse:
      type: object
      properties:
        categories:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
    BusinessUnitSearchResponse:
      type: object
      properties:
        businesses:
          type: array
          items:
            $ref: '#/components/schemas/BusinessUnitSummary'
        totalNumberOfBusinesses:
          type: integer
        currentPage:
          type: integer
        perPage:
          type: integer
    BusinessUnitProfile:
      type: object
      properties:
        id:
          type: string
        displayName:
          type: string
        name:
          type: string
        websiteUrl:
          type: string
        countryCode:
          type: string
        trustScore:
          type: number
          format: double
        stars:
          type: number
          format: double
        numberOfReviews:
          type: object
          properties:
            total:
              type: integer
            oneStar:
              type: integer
            twoStars:
              type: integer
            threeStars:
              type: integer
            fourStars:
              type: integer
            fiveStars:
              type: integer
        contact:
          type: object
          properties:
            email:
              type: string
            phone:
              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