SiteJabber Reviews API

openapi: 3.2.0
info:
  title: SmartCustomer (Sitejabber) Business 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: Reviews
paths:
  /businesses/{business}/review:
    get:
      operationId: getBusinessReview
      summary: Get a review of a business
      tags:
      - Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseEnvelope'
                - $ref: '#/components/schemas/ReviewWrapper'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/business'
      - name: review_no
        in: query
        description: number of review to be retrieved
        required: true
        schema:
          type: integer
  /businesses/{business}/reviews:
    get:
      operationId: getBusinessReviews
      summary: Get reviews of a business
      tags:
      - Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseEnvelope'
                - $ref: '#/components/schemas/ReviewListWrapper'
        '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: q
        in: query
        description: search reviews by keyword (title, content)
        required: false
        schema:
          type: string
      - name: labels
        in: query
        description: search reviews with the specified comma separated labels
        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: unpublished
        in: query
        description: include unpublished reviews (0 or 1)
        required: false
        schema:
          type: string
          default: 'false'
      - name: updated
        in: query
        description: search updated reviews (0 or 1)
        required: false
        schema:
          type: string
          default: 'false'
      - name: deleted
        in: query
        description: returns only deleted reviews (0 or 1)
        required: false
        schema:
          type: string
          default: 'false'
      - name: solicited
        in: query
        description: returns organic or solicited reviews (0 or 1), defaults to all reviews
        required: false
        schema:
          type: string
      - name: datasources
        in: query
        description: include reviews from specified comma separated data sources (check the data sources section)
        required: false
        schema:
          type: string
          default: 'false'
      - name: order
        in: query
        description: ASC/DESC order of the reviews, ascending or descending on the creation date
        required: false
        schema:
          type: string
          default: DESC
  /businesses/{business}/reviews/publish:
    post:
      operationId: publishReview
      summary: Publish an unpublished review
      tags:
      - Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelope'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/business'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                review_no:
                  type: integer
                  description: number of review to be published
              required:
              - review_no
  /businesses/{business}/reviews/flag:
    post:
      operationId: flagReview
      summary: Flag a review
      tags:
      - Reviews
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseEnvelope'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      parameters:
      - $ref: '#/components/parameters/business'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - review_no
              - reason
              - message
              properties:
                review_no:
                  type: integer
                  description: number of review to be flagged
                reason:
                  type: string
                  description: 'reason can be one of the following: language, personal_info, personal_attack, second_hand, another_biz, other. language: Review contains profanity, lewdness, or bigotry; personal_info: Review contains personal information; personal_attack: Review contains personal attacks; second_hand: Review describes second-hand experience; another_biz: Review was intended for another business; other: Other'
                  enum:
                  - language
                  - personal_info
                  - personal_attack
                  - second_hand
                  - another_biz
                  - other
                message:
                  type: string
                  description: feedback message explaining the reason
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
    Rating:
      type: object
      title: Rating Object
      required:
      - type
      - rating
      properties:
        type:
          type: string
          description: 'Possible values: overall, service, value, shipping, returns, quality'
          enum:
          - overall
          - service
          - value
          - shipping
          - returns
          - quality
        rating:
          type: number
          description: Float value between 1 and 5
          minimum: 1
          maximum: 5
    ReviewListWrapper:
      type: object
      properties:
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
    ReviewWrapper:
      type: object
      properties:
        review:
          $ref: '#/components/schemas/Review'
    ReviewImage:
      type: object
      title: ReviewImage 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
          format: date-time
    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
    Review:
      type: object
      title: Review Object
      properties:
        reviewNo:
          type: integer
          description: Review number, identifier
        rating:
          type: array
          description: Array of Rating object
          items:
            $ref: '#/components/schemas/Rating'
        title:
          type: string
          description: Title for the review
        content:
          type: string
          description: Content for the review
        tip:
          type: string
          description: Tip for the review
        order_id:
          type: string
          description: Order ID for the review
        images:
          type: array
          description: Array of customer review images
          items:
            $ref: '#/components/schemas/ReviewImage'
        positive_votes:
          type: integer
          description: Number of positive votes for the review
        negative_votes:
          type: integer
          description: Number of negative votes for the review
        created:
          type: string
          description: Review creation date
        createdRFC:
          type: string
          description: Same as created but in format RFC 3339
        published:
          type: string
          description: If the review is not yet published, it'll contain the string pending
        publishedRFC:
          type: string
          description: Same as published but in format RFC 3339
        edited:
          type: string
          description: DateTime the review was edited
        editedRFC:
          type: string
          description: Same as edited but in format RFC 3339
        removedRFC:
          type: string
          description: DateTime the review was removed in format RFC 3339 (only available if the review is removed)
        updated_for:
          $ref: '#/components/schemas/Review'
          description: If this is an updated review, this will contain the original review
        source:
          type: string
          description: Only available for solicited reviews, indicates the source
          enum:
          - BCC
          - CSV
          - WEBHOOK
          - CHECKOUT_WIDGET
          - API
          - WEB
          - QUICK_REQUEST
          - OTHER
        datasource:
          type: string
          description: Indicates the 3rd party data source (check the data sources section)
        labels:
          type: array
          description: Array of labels
          items:
            type: string
        author:
          allOf:
          - $ref: '#/components/schemas/User'
          description: Author of the review
  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/