openapi: 3.0.0
info:
  title: ZipRecruiter Jobs API
  description: |
    Search ZipRecruiter job listings in the US and Canada by location and keywords.

    Each job returns the title, company, location, job types, benefits, experience level, education, salary, posting time, description and links. Filter by posting date, work arrangement, job type, experience level and salary, and page through up to 10 pages of results.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: ZipRecruiter Jobs Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `ziprecruiter_jobs`'
          schema:
            type: string
            enum: ["ziprecruiter_jobs"]
        - name: q
          in: query
          required: false
          description: Keywords to search for, such as a job title, a skill or a company name.
          schema:
            type: string
            maxLength: 200
        - name: location
          in: query
          required: true
          description: City, state, province or postal code to search jobs in. Use `Remote` to search remote jobs across the US.
          schema:
            type: string
            maxLength: 200
        - name: country
          in: query
          required: false
          description: Country to search jobs in.
          schema:
            type: string
            enum: ["us", "ca"]
            default: "us"
        - name: distance
          in: query
          required: false
          description: Search radius around the location, in miles.
          schema:
            type: integer
            enum: [5, 10, 25, 50, 100]
            default: 25
        - name: time_period
          in: query
          required: false
          description: Posting date window of the jobs.
          schema:
            type: string
            enum: ["last_day", "last_5_days", "last_10_days", "last_30_days"]
        - name: work_arrangement
          in: query
          required: false
          description: Where the work is done. A job that can be done remotely or on site matches both `remote` and `hybrid`.
          schema:
            type: string
            enum: ["remote", "hybrid", "on_site"]
        - name: job_type
          in: query
          required: false
          description: 'Employment types to search, separated by commas. Jobs of any listed type are returned. Values: `full_time`, `part_time`, `contract`, `temporary`, `per_diem`.'
          schema:
            type: string
            pattern: '^ *(?:full_time|part_time|contract|temporary|per_diem) *(?:, *(?:full_time|part_time|contract|temporary|per_diem) *)*$'
        - name: experience_level
          in: query
          required: false
          description: 'Experience levels to search, separated by commas. Values: `no_experience`, `junior`, `mid`, `senior`.'
          schema:
            type: string
            pattern: '^ *(?:no_experience|junior|mid|senior) *(?:, *(?:no_experience|junior|mid|senior) *)*$'
        - name: salary_min
          in: query
          required: false
          description: Lowest yearly pay that the top of a job's pay range must reach.
          schema:
            type: integer
            minimum: 1
            maximum: 10000000
        - name: salary_max
          in: query
          required: false
          description: Highest yearly pay that the top of a job's pay range may reach. Must be greater than `salary_min`.
          schema:
            type: integer
            minimum: 1
            maximum: 10000000
        - name: page
          in: query
          required: false
          description: Page of results to return. Each page holds up to 20 jobs.
          schema:
            type: integer
            minimum: 1
            maximum: 10
            default: 1
        - 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'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Why there are no jobs 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 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.
        q:
          type: string
          description: Keywords the search was run for.
        location:
          type: string
          description: Location the search was run for.
        country:
          type: string
          description: Country the search was run in.
        distance:
          type: integer
          description: Search radius in miles.
        time_period:
          type: string
          description: Posting date window of the search.
        work_arrangement:
          type: string
          description: Work arrangement the search was filtered by.
        job_type:
          type: string
          description: Employment types the search was filtered by.
        experience_level:
          type: string
          description: Experience levels the search was filtered by.
        salary_min:
          type: integer
          description: Lowest yearly pay the search was filtered by.
        salary_max:
          type: integer
          description: Highest yearly pay the search was filtered by.
        page:
          type: integer
          description: Page of results requested.
    SearchInformation:
      type: object
      properties:
        query_displayed:
          type: string
          description: Keywords ZipRecruiter ran the search for.
        location_displayed:
          type: string
          description: Location ZipRecruiter ran the search for.
        distance:
          type: integer
          description: Search radius ZipRecruiter used, in miles.
        total_results:
          type: integer
          description: Number of jobs ZipRecruiter reports for the search.
    Job:
      type: object
      required: [position, title, is_remote, is_hybrid, is_easy_apply, is_new]
      properties:
        position:
          type: integer
          description: Position of the job in the results.
        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 hiring company.
        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 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"]
        experience_level:
          type: string
          description: Experience level the job asks for.
          enum: ["no_experience", "junior", "mid", "senior"]
        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: Snippet of the job description.
        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_new:
          type: boolean
          description: Whether ZipRecruiter marks the job as new.
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Page number of the results.
        total_pages:
          type: integer
          description: Number of pages ZipRecruiter shows for the search.
        next:
          type: integer
          description: Number of the next page.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
