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). SmartCustomer does not publish an OpenAPI definition; every path, parameter, default, enum and schema field below is copied from the provider''s published reference tables. Where the reference names an object but publishes no field table (ProductCategory, ProductAttribute) the schema is left open rather than invented. Response wrappers are modelled from the published example payloads and the documented status/success envelope.


    Authentication is two-part: a client_token (API key) passed as a query parameter on every call, plus a user_token request header obtained from POST /login.'
  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:
    ReviewWrapper:
      type: object
      properties:
        review:
          $ref: '#/components/schemas/Review'
    ReviewListWrapper:
      type: object
      properties:
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
    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
    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
    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
    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
    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
  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
  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'
  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/