openapi: 3.0.0
info:
  title: ZipRecruiter Job API
  description: |
    Get one ZipRecruiter job by its job id, with the full description, title, company, location, job types, benefits, education, years of experience, salary, posting time, apply and job links, and whether the job is still active.

    When ZipRecruiter shows a company profile on the job's page, it comes back as `company`.

    **Cross-linking**: `job_id` comes from `jobs[].job_id` in ZipRecruiter Jobs API results.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: ZipRecruiter Job Details
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `ziprecruiter_job`'
          schema:
            type: string
            enum: ["ziprecruiter_job"]
        - name: job_id
          in: query
          required: true
          description: Job id from ZipRecruiter Jobs API results.
          schema:
            type: string
            pattern: '^[0-9a-fA-F]{16}$'
        - 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'
        job:
          $ref: '#/components/schemas/Job'
        company:
          $ref: '#/components/schemas/Company'
        error:
          type: string
          description: Why there is no job 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 job"
        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.
        job_id:
          type: string
          description: Job id the request was run for.
    Job:
      type: object
      required: [job_id, title, is_remote, is_hybrid, is_easy_apply, is_active]
      properties:
        job_id:
          type: string
          description: ZipRecruiter identifier for the job.
        title:
          type: string
          description: Job title.
        company_id:
          type: string
          description: ZipRecruiter slug of the company page the job links to.
        company_name:
          type: string
          description: Name of the hiring company.
        company_link:
          type: string
          description: Link to the company's jobs page on ZipRecruiter.
        company_logo:
          type: string
          description: URL of the company logo.
        location:
          type: string
          description: Job location as shown on ZipRecruiter.
        city:
          type: string
          description: City of the job.
        state:
          type: string
          description: State or province code of the job.
        county:
          type: string
          description: County of the job.
        postal_code:
          type: string
          description: Postal code of the job.
        country:
          type: string
          description: Country code of the job.
        job_types:
          type: array
          description: Employment types of the job.
          items:
            type: string
            enum: ["Full-time", "Part-time", "Contractor", "Temporary", "Per diem", "Other", "Internship"]
        benefits:
          type: array
          description: Benefits offered with the job.
          items:
            type: string
            enum: ["Dental", "Medical", "Life insurance", "Paid time off", "Retirement", "Vision"]
        education:
          type: array
          description: Education the job asks for.
          items:
            type: object
            required: [level]
            properties:
              level:
                type: string
                description: Education level.
                enum: ["none_required", "high_school", "associate", "bachelors", "masters", "doctorate", "professional_certificate"]
              requirement:
                type: string
                description: Whether the education level is required or preferred.
                enum: ["required", "preferred"]
        years_of_experience:
          type: number
          description: Years of experience the job asks for.
        salary:
          type: object
          description: Pay ZipRecruiter shows for the job.
          required: [is_estimated]
          properties:
            min:
              type: number
              description: Lower bound of the pay.
            max:
              type: number
              description: Upper bound of the pay.
            period:
              type: string
              description: Period the pay is given for.
              enum: ["hour", "day", "week", "month", "year"]
            currency:
              type: string
              description: Currency of the pay.
              enum: ["AUD", "CAD", "EUR", "GBP", "USD"]
            annual_min:
              type: number
              description: Lower bound of the pay over a year.
            annual_max:
              type: number
              description: Upper bound of the pay over a year.
            is_estimated:
              type: boolean
              description: Whether ZipRecruiter estimated the pay.
        iso_date:
          type: string
          format: date-time
          description: Time the job was posted, in UTC.
        posted_at:
          type: string
          description: Relative time since the job was posted.
        description:
          type: string
          description: Full job description as plain text.
        apply_link:
          type: string
          description: Link to apply for the job on the employer's site.
        link:
          type: string
          description: Link to the job posting on ZipRecruiter.
        is_remote:
          type: boolean
          description: Whether the job can be done remotely.
        is_hybrid:
          type: boolean
          description: Whether the job is hybrid or lets you work remotely or on site.
        is_easy_apply:
          type: boolean
          description: Whether candidates can apply on ZipRecruiter itself.
        is_active:
          type: boolean
          description: Whether the job is still open on ZipRecruiter.
    Company:
      type: object
      required: [company_id, name, link]
      properties:
        company_id:
          type: string
          description: ZipRecruiter slug of the company's profile, which can differ from the job's company_id.
        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.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
