openapi: 3.0.0
info:
  title: Capterra Reviews API
  description: |
    Get the reviews of a software product on Capterra, 25 per page: Capterra's default review feed, or reviews sorted by most helpful, most recent, highest or lowest rating and filtered by rating, company size, reviewer role, length of use and frequency of use.

    Each review carries its overall and detailed ratings, title, summary, pros and cons, date, incentive source, and the reviewer's name, job title, industry, company size, length of use and verification. The response also returns the product's name, vendor, category, overall and detailed ratings, review count and pricing.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Capterra Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `capterra_reviews`'
          schema:
            type: string
            enum: ["capterra_reviews"]
        - name: url
          in: query
          required: true
          description: The product's Capterra URL, such as `https://www.capterra.com/p/135003/Slack/reviews/`. Any page of the product is accepted.
          schema:
            type: string
        - name: sort_by
          in: query
          required: false
          description: Order of reviews. Without it and without filters, the reviews come in Capterra's default feed, which pages up to 100 pages and includes summaries of reviews Capterra shows only to signed-in visitors.
          schema:
            type: string
            enum: ["most_helpful", "most_recent", "highest_rated", "lowest_rated"]
        - name: rating
          in: query
          required: false
          description: Only reviews with these star ratings, from 1 to 5, separated by commas.
          schema:
            type: string
        - name: company_size
          in: query
          required: false
          description: 'Only reviewers from companies of these sizes, separated by commas: `self_employed`, `1_10`, `11_50`, `51_200`, `201_500`, `501_1000`, `1001_5000`, `5001_10000` or `10001_plus`.'
          schema:
            type: string
        - name: reviewer_role
          in: query
          required: false
          description: 'Only reviewers with these roles, separated by commas: `user`, `administrator` or `other`.'
          schema:
            type: string
        - name: time_used
          in: query
          required: false
          description: 'Only reviewers who used the product for these lengths of time, separated by commas: `free_trial`, `less_than_6_months`, `6_12_months`, `1_2_years` or `2_plus_years`.'
          schema:
            type: string
        - name: usage_frequency
          in: query
          required: false
          description: 'Only reviewers who use the product this often, separated by commas: `daily`, `weekly`, `monthly` or `other`.'
          schema:
            type: string
        - name: next_page_token
          in: query
          required: false
          description: The `pagination.next_page_token` from the previous page, sent with the same `url`, `sort_by` and filters, to get the next 25 reviews.
          schema:
            type: string
            pattern: '^[A-Za-z0-9+/=_-]{8,2048}$'
            maxLength: 2048
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          type: object
          properties:
            total_results:
              type: integer
              description: Number of reviews matching the filters.
        product:
          type: object
          required: [product_id, name, link]
          properties:
            product_id:
              type: string
              description: Capterra product ID.
            name:
              type: string
              description: Product name.
            link:
              type: string
              description: The product's reviews page on Capterra.
            vendor:
              type: string
              description: Company that makes the product.
            logo:
              type: string
              description: Product logo URL.
            category:
              type: string
              description: The product's main Capterra category.
            description:
              type: string
              description: The product's description.
            target_market:
              type: string
              description: Who the product is for.
            rating:
              type: number
              description: Average rating on a 1-5 scale.
            reviews_count:
              type: integer
              description: Total number of reviews.
            ratings:
              $ref: '#/components/schemas/Ratings'
            pricing:
              type: object
              properties:
                starting_price:
                  type: number
                  description: Starting price of the default plan.
                currency:
                  type: string
                  description: Price currency code.
                plan:
                  type: string
                  description: Name of the default plan.
                billing_period:
                  type: string
                  description: How often the starting price is billed.
                pricing_model:
                  type: string
                  description: What the starting price is charged for, such as Per User.
                has_free_trial:
                  type: boolean
                  description: Whether the product offers a free trial.
                has_free_version:
                  type: boolean
                  description: Whether the product has a free version.
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
        pagination:
          type: object
          properties:
            next_page_token:
              type: string
              description: Token for the next page of reviews.
        error:
          type: string
          description: Why there are no reviews to return.
    Ratings:
      type: object
      properties:
        ease_of_use:
          type: number
          description: Ease of use rating from 1 to 5, where 0 means the reviewer did not rate it.
        customer_service:
          type: number
          description: Customer service rating from 1 to 5, where 0 means the reviewer did not rate it.
        features:
          type: number
          description: Features rating from 1 to 5, where 0 means the reviewer did not rate it.
        value_for_money:
          type: number
          description: Value for money rating from 1 to 5, where 0 means the reviewer did not rate it.
        likelihood_to_recommend:
          type: number
          description: Likelihood to recommend on a 0-10 scale.
    Product:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Product name.
        link:
          type: string
          description: The product's page on Capterra.
        logo:
          type: string
          description: Product logo URL.
    Review:
      type: object
      required: [position, review_id, rating]
      properties:
        position:
          type: integer
          description: Position of the review on this page.
        review_id:
          type: string
          description: Capterra review ID.
        title:
          type: string
          description: Review title.
        rating:
          type: number
          description: Overall rating on a 1-5 scale.
        date:
          type: string
          format: date
          description: 'Date the review was written. Format: YYYY-MM-DD'
        summary:
          type: string
          description: The reviewer's overall comments.
        pros:
          type: string
          description: What the reviewer likes.
        cons:
          type: string
          description: What the reviewer dislikes.
        advice:
          type: string
          description: The reviewer's advice to others.
        reasons_for_choosing:
          type: string
          description: Why the reviewer chose this product.
        reasons_for_switching:
          type: string
          description: Why the reviewer switched to this product.
        ratings:
          $ref: '#/components/schemas/Ratings'
        review_source:
          type: string
          description: How the review was collected, such as No Incentive Offered or Nominal Gift Card.
        is_incentivized:
          type: boolean
          description: Whether the reviewer was offered an incentive.
        source_site:
          type: string
          description: Site the review was written on, such as Capterra, GetApp or G2.
        is_summary:
          type: boolean
          description: Whether the review is a summary of a review Capterra shows in full only to signed-in visitors.
        reviewer:
          type: object
          required: [name]
          properties:
            name:
              type: string
              description: Reviewer name as shown.
            job_title:
              type: string
              description: Reviewer job title.
            industry:
              type: string
              description: Reviewer industry.
            company_size:
              type: string
              description: Size of the reviewer's company.
            time_used:
              type: string
              description: How long the reviewer used the product.
            avatar:
              type: string
              description: Reviewer photo URL.
            is_anonymous:
              type: boolean
              description: Whether the reviewer chose to stay anonymous.
            is_linkedin_verified:
              type: boolean
              description: Whether the reviewer's LinkedIn profile is verified.
            validations:
              type: array
              description: Checks the reviewer passed, such as LinkedIn or BusinessEmail.
              items:
                type: string
        alternatives_considered:
          type: array
          description: Other products the reviewer considered.
          items:
            $ref: '#/components/schemas/Product'
        switched_from:
          type: array
          description: Products the reviewer switched from.
          items:
            $ref: '#/components/schemas/Product'
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Capterra URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
        url:
          type: string
        sort_by:
          type: string
          enum: ["most_helpful", "most_recent", "highest_rated", "lowest_rated"]
        rating:
          type: string
        company_size:
          type: string
        reviewer_role:
          type: string
        time_used:
          type: string
        usage_frequency:
          type: string
        next_page_token:
          type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong