openapi: 3.0.0
info:
  title: Indeed Company Reviews API
  description: |
    Get employee reviews for a company on Indeed.

    Each review returns its rating, title, text, pros and cons, five sub-ratings, the reviewer's job title and location, and the date. The response also carries a company summary (overall rating, review count, category ratings, top pros and cons) and pagination. Use `gl` to read a country's Indeed site.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Indeed Company Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `indeed_company_reviews`'
          schema:
            type: string
            enum: ["indeed_company_reviews"]
        - name: company_id
          in: query
          required: true
          description: Indeed company identifier, the slug in a company's Indeed URL, such as `Amazon.com` or `Pearson-9e5c0404`.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page of reviews, starting at 1. Each page returns up to 20 reviews.
          schema:
            type: integer
            default: 1
            maximum: 107374183
        - name: sort
          in: query
          required: false
          description: Order of the reviews.
          schema:
            type: string
            enum: ["date_desc", "rating_desc", "rating_asc"]
            default: "date_desc"
        - name: gl
          in: query
          required: false
          description: Country whose Indeed site to read, as an ISO 3166-1 alpha-2 code.
          schema:
            type: string
            enum: ["us", "gb", "ca", "au", "ie", "nz", "in", "sg", "ph", "my", "hk", "pk", "de", "fr", "es", "it", "nl", "be", "at", "ch", "pl", "se", "no", "dk", "fi", "pt", "ro", "cz", "hu", "gr", "br", "mx", "ar", "cl", "co", "pe", "jp", "kr", "tr", "ae", "za", "ng", "eg"]
            default: "us"
      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
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        company:
          $ref: '#/components/schemas/Company'
        reviews:
          type: array
          items:
            $ref: '#/components/schemas/Review'
        pagination:
          $ref: '#/components/schemas/Pagination'
    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: "Indeed 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
          description: Search engine used for the request.
        company_id:
          type: string
          description: Company identifier the reviews were read for.
        page:
          type: integer
          description: Page of reviews returned.
        sort:
          type: string
          description: Order the reviews were returned in.
        gl:
          type: string
          description: Country whose Indeed site was read.
    Company:
      type: object
      properties:
        name:
          type: string
          description: Company name.
        logo:
          type: string
          description: URL of the company logo.
        link:
          type: string
          description: Link to the company's reviews on Indeed.
        reviews_histogram:
          $ref: '#/components/schemas/ReviewsHistogram'
        wellbeing:
          $ref: '#/components/schemas/Wellbeing'
        topics:
          type: array
          description: Review topics with their review count and rating.
          items:
            $ref: '#/components/schemas/Topic'
        rating:
          type: number
          description: Overall company rating out of five.
        reviews_count:
          type: integer
          description: Total number of reviews for the company.
        found_reviews_count:
          type: integer
          description: Number of reviews in the current country view.
        ratings:
          $ref: '#/components/schemas/CategoryRatings'
        pros:
          type: array
          description: Most common positive themes across reviews.
          items:
            type: string
        cons:
          type: array
          description: Most common negative themes across reviews.
          items:
            type: string
    ReviewsHistogram:
      type: object
      description: Number of reviews at each star rating, across all of the company's reviews.
      properties:
        '1':
          type: integer
          description: Number of 1-star reviews.
        '2':
          type: integer
          description: Number of 2-star reviews.
        '3':
          type: integer
          description: Number of 3-star reviews.
        '4':
          type: integer
          description: Number of 4-star reviews.
        '5':
          type: integer
          description: Number of 5-star reviews.
    Wellbeing:
      type: object
      description: Indeed's work wellbeing score, separate from star ratings.
      properties:
        score:
          type: integer
          description: Wellbeing score out of 100.
        grade:
          type: string
          description: Grade Indeed gives the score.
        survey_count:
          type: integer
          description: Number of survey responses behind the score.
    Topic:
      type: object
      properties:
        id:
          type: string
          description: Indeed identifier for the topic.
        name:
          type: string
          description: Topic name.
        reviews:
          type: integer
          description: Number of reviews that rate this topic.
        rating:
          type: number
          description: Average rating for this topic.
    CategoryRatings:
      type: object
      properties:
        work_life_balance:
          type: number
          description: Average work-life balance rating.
        compensation_benefits:
          type: number
          description: Average compensation and benefits rating.
        job_security_advancement:
          type: number
          description: Average job security and advancement rating.
        management:
          type: number
          description: Average management rating.
        culture:
          type: number
          description: Average culture rating.
    Review:
      type: object
      required: [position, review_id, text, rating, link]
      properties:
        position:
          type: integer
          description: Position of the review on the page.
        review_id:
          type: string
          description: Indeed identifier for the review.
        title:
          type: string
          description: Review title.
        text:
          type: string
          description: Review text.
        rating:
          type: integer
          description: Overall rating out of five.
        subratings:
          type: object
          description: Sub-ratings for the review, each out of five.
          properties:
            work_life_balance:
              type: integer
              description: Work-life balance rating.
            compensation_benefits:
              type: integer
              description: Compensation and benefits rating.
            job_security_advancement:
              type: integer
              description: Job security and advancement rating.
            management:
              type: integer
              description: Management rating.
            culture:
              type: integer
              description: Culture rating.
        pros:
          type: string
          description: Positive points from the review.
        cons:
          type: string
          description: Negative points from the review.
        job_title:
          type: string
          description: Job title of the reviewer.
        normalized_job_title:
          type: string
          description: Standard role Indeed maps the job title to.
        location:
          type: string
          description: Location of the reviewer.
        country:
          type: string
          description: Country code of the reviewer.
        date:
          type: string
          description: Date the review was posted, as shown on Indeed.
        iso_date:
          type: string
          description: Date the review was posted, as YYYY-MM-DD when available.
        helpful_count:
          type: integer
          description: Number of people who marked the review helpful.
        unhelpful_count:
          type: integer
          description: Number of people who marked the review unhelpful.
        is_current_employee:
          type: boolean
          description: Whether the reviewer is a current employee.
        link:
          type: string
          description: Link to the review on Indeed.
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          description: Current page of reviews.
        reviews_per_page:
          type: integer
          description: Number of reviews per page.
        total_reviews:
          type: integer
          description: Total number of reviews available.
        next_page:
          type: integer
          description: Value to pass as page to get the next page of reviews.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong