openapi: 3.0.0
info:
  title: ZipRecruiter Company API
  description: |
    Get a company's ZipRecruiter profile by its company id: name, website, logo, industries, size, founded year, headquarters with its street address, about text, social links and the companies ZipRecruiter lists as similar.

    **Cross-linking**: `company_id` comes from `company.company_id` in ZipRecruiter Job API results or `jobs[].company_id` in ZipRecruiter Jobs API results.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: ZipRecruiter Company Profile
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `ziprecruiter_company`'
          schema:
            type: string
            enum: ["ziprecruiter_company"]
        - name: company_id
          in: query
          required: true
          description: Company slug from ZipRecruiter Job or ZipRecruiter Jobs API results, in any case.
          schema:
            type: string
            maxLength: 200
        - name: zero_retention
          in: query
          required: false
          description: Set to true to disable logging and persistent storage for this request. Enterprise plans only.
          schema:
            type: boolean
            default: false
      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'
        '403':
          description: Forbidden. Zero data retention is not available to the account, or the account requires `zero_retention=true`.
          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'
        error:
          type: string
          description: Why there is no company profile to return.
    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: "ZipRecruiter URL for this company"
        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 slug the request was run for.
    Company:
      type: object
      required: [company_id, name, link]
      properties:
        company_id:
          type: string
          description: ZipRecruiter slug of the company's profile, which an alias of the company resolves to.
        name:
          type: string
          description: Name of the company.
        link:
          type: string
          description: Link to the company's jobs page on ZipRecruiter.
        logo:
          type: string
          description: URL of the company logo.
        website:
          type: string
          description: Company website.
        industries:
          type: array
          description: Industries the company works in.
          items:
            type: string
        size:
          type: string
          description: Number of employees as shown on ZipRecruiter.
        founded_year:
          type: integer
          description: Year the company was founded.
        headquarters:
          type: string
          description: Location of the company headquarters.
        about:
          type: string
          description: Description of the company.
        facebook_link:
          type: string
          description: Company Facebook page.
        instagram_link:
          type: string
          description: Company Instagram page.
        twitter_link:
          type: string
          description: Company X (Twitter) page.
        address:
          type: object
          description: Address of the company headquarters.
          properties:
            street:
              type: string
              description: Street address.
            city:
              type: string
              description: City.
            state:
              type: string
              description: State or province.
            postal_code:
              type: string
              description: Postal code.
            country:
              type: string
              description: Two-letter country code.
        similar_companies:
          type: array
          description: Companies ZipRecruiter lists as similar.
          items:
            $ref: '#/components/schemas/SimilarCompany'
    SimilarCompany:
      type: object
      required: [company_id, name, link]
      properties:
        company_id:
          type: string
          description: ZipRecruiter slug of the company's profile.
        name:
          type: string
          description: Name of the company.
        link:
          type: string
          description: Link to the company's jobs page on ZipRecruiter.
        logo:
          type: string
          description: URL of the company logo.
        city:
          type: string
          description: City of the company headquarters.
        state:
          type: string
          description: State or province of the company headquarters.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
