SiteJabber Product Reviews API

openapi: 3.2.0
info:
  title: SmartCustomer (Sitejabber) Business Product Reviews API
  version: v1
  summary: Business review, product review, review request, messaging and privacy API for SmartCustomer (formerly Sitejabber).
  description: 'Transcribed by API Evangelist from SmartCustomer''s own published API reference at https://api.sitejabber.com/ (Slate source: https://github.com/smartcustomer-reviews/business-api-docs).'
  contact:
    name: SmartCustomer API Support
    email: support@smartcustomer.com
    url: https://api.sitejabber.com/
  termsOfService: https://www.smartcustomer.com/terms
  x-transcribed-by: API Evangelist enrichment pipeline
  x-transcription-source: https://api.sitejabber.com/
servers:
- url: https://api.smartcustomer.com/v1
  description: Production. The same reference is also served from https://api.sitejabber.com/ under the pre-rebrand Sitejabber name.
security:
- client_token: []
  user_token: []
tags:
- name: Product Reviews
paths:
  /businesses/{business}/product/reviews:
    get:
      operationId: getProductReviews
      summary: Get product reviews
      tags:
      - Product Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseEnvelope'
                - $ref: '#/components/schemas/ProductReviewListWrapper'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/business'
      - name: start
        in: query
        description: starting offset
        required: false
        schema:
          type: integer
          default: 0
      - name: count
        in: query
        description: number of reviews to be included (max 100)
        required: false
        schema:
          type: integer
          default: 10
      - name: sku
        in: query
        description: retrieve reviews for the given product sku
        required: false
        schema:
          type: string
      - name: item_group
        in: query
        description: retrieve reviews for the given group of products, if specified, sku is ignored
        required: false
        schema:
          type: string
      - name: q
        in: query
        description: retrieve product reviews matching given keywords
        required: false
        schema:
          type: string
      - name: brand
        in: query
        description: retrieve products matching brand
        required: false
        schema:
          type: string
      - name: categories
        in: query
        description: retrieve products in the given categories
        required: false
        schema:
          type: string
      - name: only_photos
        in: query
        description: retrieve product reviews containing customer product images, default 0 (1=Yes, 0=No)
        required: false
        schema:
          type: string
      - name: price_range
        in: query
        description: retrieve products in the given prices [min],[max]
        required: false
        schema:
          type: string
      - name: reviews_range
        in: query
        description: retrieve products with the given number of reviews [min],[max]
        required: false
        schema:
          type: string
      - name: ratings
        in: query
        description: returns only product reviews with the specified comma separated ratings, for example (3,4,5), defaults to all ratings
        required: false
        schema:
          type: string
      - name: deleted
        in: query
        description: returns only deleted product reviews (0 or 1)
        required: false
        schema:
          type: string
      - name: date_from
        in: query
        description: start date in format (yyyy-mm-dd hh:mm:ss) [hh:mm:ss] is optional
        required: false
        schema:
          type: string
      - name: date_to
        in: query
        description: end date in format (yyyy-mm-dd hh:mm:ss) [hh:mm:ss] is optional
        required: false
        schema:
          type: string
      - name: order
        in: query
        description: specifies the order (created=most recent, relevant=most relevant), defaults to most recent
        required: false
        schema:
          type: string
  /businesses/{business}/product/reviews/add:
    post:
      operationId: addProductReview
      summary: Add product review
      tags:
      - Product Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelope'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: image{n} / caption{n} repeat for each additional image (image2/caption2, image3/caption3, ...).
      parameters:
      - $ref: '#/components/parameters/business'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                sku:
                  type: string
                  description: product SKU
                title:
                  type: string
                  description: product review title
                content:
                  type: string
                  description: product review content
                rating:
                  type: integer
                  description: product review rating
                order_id:
                  type: string
                  description: product review order id
                first_name:
                  type: string
                  description: first name of the user writing the review
                last_name:
                  type: string
                  description: last name of the user writing the review
                email:
                  type: string
                  description: email of the user writing the review
                user_location:
                  type: string
                  description: location of the user writing the review
                location:
                  type: string
                  description: business location identifier
                attributes:
                  type: string
                  description: values of attributes defined for the product
                image1:
                  type: string
                  description: can be used to send multiple images (image1, image2, ...., image{n}); it can be image binary data or a url pointing to an image file. The images are uploaded in the order specified.
                caption1:
                  type: string
                  description: can be used to set a caption for the image (caption1, caption2, ...., caption{n})
              required:
              - sku
              - title
              - content
              - rating
  /businesses/{business}/product/reviews/vote:
    post:
      operationId: addProductReviewVote
      summary: Add product review vote
      tags:
      - Product Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelope'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      description: A user can vote only once every 24 hours (error code 404).
      parameters:
      - $ref: '#/components/parameters/business'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - review_id
              - vote
              properties:
                review_id:
                  type: integer
                  description: product review ID
                vote:
                  type: string
                  description: type of vote (positive/negative)
                  enum:
                  - positive
                  - negative
  /businesses/{business}/product/reviews/top-rated:
    get:
      operationId: getTopRatedProduct
      summary: Get top rated product
      tags:
      - Product Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseEnvelope'
                - $ref: '#/components/schemas/ProductListWrapper'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/business'
      - name: category_name
        in: query
        description: The name of category to get the top rated product
        required: false
        schema:
          type: string
      - name: currency
        in: query
        description: Add currency filter, used to filter by country
        required: false
        schema:
          type: string
  /businesses/{business}/product/reviews/stats:
    get:
      operationId: getProductReviewsStats
      summary: Get product reviews stats
      tags:
      - Product Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelope'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/business'
      - name: sku
        in: query
        description: retrieve stats for the given product sku
        required: false
        schema:
          type: string
      - name: categories
        in: query
        description: retrieve stats for products in the given categories (separated by commas)
        required: false
        schema:
          type: string
      - name: item_group
        in: query
        description: retrieve stats for the given group of products, if specified sku is ignored
        required: false
        schema:
          type: string
      - name: brand
        in: query
        description: retrieve stats for products in the given brand
        required: false
        schema:
          type: string
components:
  schemas:
    ResponseEnvelope:
      type: object
      description: Every response carries a success flag and a status key. When success is false and status is ERROR, errorCode and errorReason are present.
      properties:
        status:
          type: string
          description: OK if everything went good, ERROR if there was an error processing the request
        success:
          type: boolean
          description: true or false
        errorCode:
          type: integer
          description: Error code, only present when status is ERROR
        errorReason:
          type: string
          description: Error message, only present when status is ERROR
    ProductCategory:
      type: object
      title: ProductCategory Object
      description: Product category. The reference names this object on Product.categories but does not publish a field table for it.
      additionalProperties: true
    ProductReviewListWrapper:
      type: object
      properties:
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/ProductReview'
    ProductListWrapper:
      type: object
      properties:
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
    Product:
      type: object
      title: Product Object
      properties:
        id:
          type: integer
          description: Internal product ID
        sku:
          type: string
          description: SKU of the product
        item_group:
          type: string
          description: Used to group similar products together
        gtin:
          type: string
          description: GTIN of the product
        mpn:
          type: string
          description: MPN of the product
        brand:
          type: string
          description: Brand of the product
        title:
          type: string
          description: Title of the product
        description:
          type: string
          description: Description of the product
        categories:
          type: array
          description: Product categories
          items:
            $ref: '#/components/schemas/ProductCategory'
        price:
          type: number
          description: Price of the product
        retail_price:
          type: number
          description: Retail price of the product
        currency:
          type: string
          description: Currency of the product
        product_link:
          type: string
          description: Url link to the product's page
        images:
          type: array
          description: Product images
          items:
            $ref: '#/components/schemas/ProductImage'
        attributes:
          type: array
          description: Customer attributes
          items:
            $ref: '#/components/schemas/ProductAttribute'
        num_reviews:
          type: integer
          description: Number of product reviews
        average_rating:
          type: number
          description: Average rating of the product reviews
        created:
          type: string
          description: Creation date of the product
        createdRFC:
          type: string
          description: Same as created but in format RFC 3339
    ProductAttribute:
      type: object
      title: ProductAttribute Object
      description: Custom product attribute. The reference names this object on Product.attributes / ProductReview.attributes but does not publish a field table for it.
      additionalProperties: true
    User:
      type: object
      title: User Object
      required:
      - username
      - firstName
      - lastName
      - thumbnail
      - profilePage
      - numReviews
      - numHelpfulVotes
      properties:
        username:
          type: string
          description: Username of the user
        firstName:
          type: string
          description: First name of the user
        lastName:
          type: string
          description: First letter of last name of the user
        thumbnail:
          type: string
          description: Relative path of the user's thumbnail image
        profilePage:
          type: string
          description: Url of the user's profile page
        numReviews:
          type: integer
          description: Number of reviews written by the user
        numHelpfulVotes:
          type: integer
          description: Number of helpful votes received
        email:
          type: string
          description: Only available for solicited reviews and when the email of the user was provided by the business
    ProductReview:
      type: object
      title: ProductReview Object
      properties:
        id:
          type: integer
          description: Internal product review ID
        title:
          type: string
          description: Title of the review
        content:
          type: string
          description: Content of the review
        rating:
          type: integer
          description: Rating of the review
        order_id:
          type: string
          description: Order number for the review
        user:
          allOf:
          - $ref: '#/components/schemas/User'
          description: Author of the review
        user_location:
          type: string
          description: Location of the user
        attributes:
          type: array
          description: Custom attributes
          items:
            $ref: '#/components/schemas/ProductAttribute'
        images:
          type: array
          description: Array of customer product images
          items:
            $ref: '#/components/schemas/ProductImage'
        solicited:
          type: integer
          description: Defines if the review was solicited or not, values are Yes/No
        votes:
          type: integer
          description: Number of votes
        num_positive_votes:
          type: integer
          description: Number of positive votes
        num_negative_votes:
          type: integer
          description: Number of negative votes
        published:
          type: string
          description: Publication date of the product
        publishedRFC:
          type: string
          description: Same as published but in format RFC 3339
        created:
          type: string
          description: Creation date of the product
        createdRFC:
          type: string
          description: Same as created but in format RFC 3339
        product:
          allOf:
          - $ref: '#/components/schemas/Product'
          description: Product of the review
        removedRFC:
          type: string
          description: DateTime the product review was removed in format RFC 3339 (only available if the product review is removed)
    ProductImage:
      type: object
      title: ProductImage Object
      properties:
        caption:
          type: string
          description: Caption of the image
        original:
          type: string
          description: Url of the image original size
        normal:
          type: string
          description: Url of the image normal size, max width 600px
        large:
          type: string
          description: Url of the image thumbnail large size 160x160
        small:
          type: string
          description: Url of the image thumbnail small size 96x96
        created:
          type: string
          description: Creation date of the image
        createdRFC:
          type: string
          description: Same as created but in format RFC 3339
  responses:
    TooManyRequests:
      description: Too many requests. 1000 calls per hour per unique user token; no more than 10 calls in a 10 second window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseEnvelope'
  parameters:
    business:
      name: business
      in: path
      required: true
      description: The business's display address (domain without scheme), e.g. yourdomain.com
      schema:
        type: string
      example: yourdomain.com
  securitySchemes:
    client_token:
      type: apiKey
      in: query
      name: client_token
      description: API key issued to the business, passed as a query parameter on every request.
    user_token:
      type: apiKey
      in: header
      name: user_token
      description: User session token returned by POST /login. Typically expires after 6 months; calling login invalidates any previous token.
externalDocs:
  description: SmartCustomer API reference
  url: https://api.sitejabber.com/