openapi: 3.0.0
info:
  title: Indeed Company Salaries API
  description: |
    Get the salaries at one company on Indeed, for the whole company or for one job title.

    Without `q`, the response lists the company's salaries by job category, with each title's median pay, pay period and number of salaries reported, plus the company's total salary count, rating and salary satisfaction. With `q`, it returns that job title's average, low and high pay at the company, the national average and the difference from it, the top-paying cities and other salaries in the same category. Use `location` for a city or state and `gl` to read a country's Indeed site.

    **Cross-linking**: take `company_id` from the `/cmp/` slug of a `company_link` in `indeed_jobs` results when present, from a linked `top_paying_companies` entry's `company_id` in `indeed_salaries` results, or from the company's Indeed URL.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Indeed Company Salaries Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `indeed_company_salaries`'
          schema:
            type: string
            enum: ["indeed_company_salaries"]
        - name: company_id
          in: query
          required: true
          description: The company's Indeed id, as in `indeed.com/cmp/<company_id>`, such as `Amazon.com` or `Google`.
          schema:
            type: string
            maxLength: 200
        - name: q
          in: query
          required: false
          description: Job title at the company, such as `Software Engineer`. Omit it for the company's salaries by category.
          schema:
            type: string
            maxLength: 200
        - name: location
          in: query
          required: false
          description: City and state such as `Seattle, WA`, a state such as `California`, or a city. Omit it for the whole country.
          schema:
            type: string
            maxLength: 200
        - name: period
          in: query
          required: false
          description: Pay period for the job title's figures, where Indeed has that period (`salary.period` shows the one returned). Requires `q`.
          schema:
            type: string
            enum: ["hourly", "daily", "weekly", "monthly", "yearly"]
        - 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", "ae", "ar", "at", "au", "be", "br", "ca", "ch", "cl", "co", "cz", "de", "dk", "eg", "es", "fi", "fr", "gb", "hk", "hu", "ie", "in", "it", "jp", "mx", "my", "ng", "nl", "no", "nz", "pe", "ph", "pk", "pl", "pt", "ro", "se", "sg", "tr", "za"]
            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
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        error:
          type: string
          description: Why Indeed has no salaries for this company, job title or location.
        search_information:
          type: object
          required: [salaries_count]
          properties:
            job_title:
              type: string
              description: Job title Indeed shows the salaries for.
            location:
              type: string
              description: Location the salaries cover.
            salaries_count:
              type: integer
              description: Number of salaries the figures are based on.
            last_updated:
              type: string
              description: Date Indeed last updated the salaries, as Indeed displays it.
        company:
          type: object
          required: [name]
          properties:
            name:
              type: string
              description: Company name.
            rating:
              type: number
              description: Company rating out of 5.
            reviews_count:
              type: integer
              description: Number of company reviews.
            logo:
              type: string
              description: URL of the company logo.
            reviews_link:
              type: string
              description: Link to the company's reviews on Indeed.
            wellbeing:
              type: object
              properties:
                score:
                  type: integer
                  description: Work wellbeing score out of 100.
                grade:
                  type: string
                  description: Work wellbeing grade.
        salary:
          type: object
          description: Pay for the job title at the company.
          required: [average, period]
          properties:
            average:
              type: number
              description: Average pay in the period.
            low:
              type: number
              description: Lowest pay Indeed shows in the period.
            high:
              type: number
              description: Highest pay Indeed shows in the period.
            period:
              type: string
              description: Pay period of the figures.
              enum: ["hourly", "daily", "weekly", "monthly", "yearly"]
            most_common_period:
              type: string
              description: Pay period most salaries for this job title are reported in.
              enum: ["hourly", "daily", "weekly", "monthly", "yearly"]
            national_average:
              type: number
              description: National average pay for the job title in the same period.
            difference_from_national_average:
              type: integer
              description: Percentage the company's average differs from the national average, positive when above it and negative when below.
            salaries_link:
              type: string
              description: Link to the job title's salaries across all employers on Indeed, in the requested location when one is given.
        salary_satisfaction:
          type: object
          properties:
            fair_pay_percentage:
              type: integer
              description: Percentage of employees who say they are paid fairly.
            ratings_count:
              type: integer
              description: Number of employees who answered.
        top_paying_cities:
          type: array
          description: Cities where the job title pays the most across all employers on Indeed.
          items:
            type: object
            required: [location, salary, average]
            properties:
              location:
                type: string
                description: City and state.
              salary:
                type: string
                description: Pay as Indeed displays it.
              average:
                type: number
                description: Average pay for the job title in the city across all employers, as a number.
              period:
                type: string
                description: Pay period.
        categories:
          type: array
          description: Salaries at the company grouped by job category.
          items:
            type: object
            required: [name, salaries]
            properties:
              name:
                type: string
                description: Job category name.
              salaries:
                type: array
                items:
                  $ref: '#/components/schemas/JobSalary'
    JobSalary:
      type: object
      required: [title, salary, median, period]
      properties:
        title:
          type: string
          description: Job title.
        salary:
          type: string
          description: Median pay as Indeed displays it.
        median:
          type: number
          description: Median pay as a number.
        period:
          type: string
          description: Pay period.
          enum: ["hourly", "daily", "weekly", "monthly", "yearly"]
        salaries_count:
          type: integer
          description: Number of salaries reported for the job title.
        link:
          type: string
          description: Link to the job title's salaries at the company on Indeed.
    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
        company_id:
          type: string
        q:
          type: string
        location:
          type: string
        period:
          type: string
        gl:
          type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong