> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hirehive.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get jobs
> Get a paginated list of jobs
## OpenAPI
````yaml get /api/v2/jobs
openapi: 3.0.1
info:
title: HireHive Jobs API
description: >-
API to get a paginated list of published jobs. You can also get a job by Id
or a list of categories with the count of published jobs in those
categories.
This will return live data. If your company does not have any
published positions you can use our test account to play around with our
API. Use
HireHive test account
View Codepen
Examples
termsOfService: https://www.hirehive.com/terms-of-service/
contact:
email: support@hirehive.com
version: v2
servers:
- url: https://hirehive-testing-account.hirehive.com
security: []
paths:
/api/v2/jobs:
get:
tags:
- JobsAPIV2
summary: Get a paginated list of published jobs
parameters:
- name: sort
in: query
description: >-
Sortable fields: `title`, `published_date`. Default is
`published_date desc`. Add ` desc` to sort in descending order.
schema:
type: string
description: >-
Sortable fields: `title`, `published_date`. Default is
`published_date desc`. Add ` desc` to sort in descending order.
- name: title
in: query
description: Filter jobs by title
schema:
type: string
description: Filter jobs by title
- name: types
in: query
description: Filter jobs by employment type
schema:
type: array
items:
$ref: '#/components/schemas/EmploymentType'
description: Filter jobs by employment type
- name: experiences
in: query
description: Filter jobs by experience level
schema:
type: array
items:
$ref: '#/components/schemas/Experience'
description: Filter jobs by experience level
- name: countries
in: query
description: Filter jobs by the 2 letter ISO code of the country eg. US, FR
schema:
type: array
items:
type: string
description: Filter jobs by the 2 letter ISO code of the country eg. US, FR
- name: states
in: query
description: Filter jobs by the 2 letter ISO code of the state eg. FL, MA
schema:
type: array
items:
type: string
description: Filter jobs by the 2 letter ISO code of the state eg. FL, MA
- name: category_ids
in: query
description: Filter jobs by category id
schema:
type: array
items:
type: integer
format: int32
description: Filter jobs by category id
- name: published_after
in: query
description: Filter jobs published after a specific date
schema:
type: string
description: Filter jobs published after a specific date
format: date-time
- name: published_before
in: query
description: Filter jobs published before a specific date
schema:
type: string
description: Filter jobs published before a specific date
format: date-time
- name: page
in: query
description: Defaults to 1
required: true
schema:
type: integer
description: Defaults to 1
format: int32
- name: page_size
in: query
description: Defaults to 30. Min = 1. Max = 100
required: true
schema:
maximum: 100
minimum: 1
type: integer
description: Defaults to 30. Min = 1. Max = 100
format: int32
- name: source
in: query
description: >-
The source of the view/application that will be attributed in
reports. Default CareerSite
schema:
type: string
responses:
'200':
description: >-
Jobs = An array of jobs, PublishedJobsCount = Count of the current
published jobs, NextPage = A URL for the next page of results if
more exist
content:
application/json:
schema:
$ref: '#/components/schemas/JobAPIV2PagedResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationProblemDetails'
'404':
description: Company not found
'500':
description: Oops! Server error
components:
schemas:
EmploymentType:
enum:
- full_time
- part_time
- contract
- temporary
- other
- internship
- volunteer
type: string
Experience:
enum:
- na
- intern
- entry_level
- mid_level
- senior
type: string
JobAPIV2PagedResponse:
required:
- items
type: object
properties:
meta:
$ref: '#/components/schemas/Meta'
links:
$ref: '#/components/schemas/Links'
items:
type: array
items:
$ref: '#/components/schemas/JobAPIV2'
nullable: true
additionalProperties: false
ValidationProblemDetails:
type: object
properties:
type:
type: string
nullable: true
title:
type: string
nullable: true
status:
type: integer
format: int32
nullable: true
detail:
type: string
nullable: true
instance:
type: string
nullable: true
errors:
type: object
additionalProperties:
type: array
items:
type: string
nullable: true
additionalProperties: {}
Meta:
required:
- has_next_page
- has_previous_page
- page
- page_size
- total_items
- total_pages
type: object
properties:
page_size:
type: integer
format: int32
page:
type: integer
format: int32
total_items:
type: integer
format: int32
total_pages:
type: integer
format: int32
has_next_page:
type: boolean
has_previous_page:
type: boolean
additionalProperties: false
Links:
type: object
properties:
first:
type: string
nullable: true
last:
type: string
nullable: true
next:
type: string
nullable: true
previous:
type: string
nullable: true
additionalProperties: false
JobAPIV2:
type: object
properties:
id:
type: integer
description: The id of the job, format `job_abc123`.
format: int32
title:
type: string
nullable: true
location:
type: string
nullable: true
state_code:
type: string
nullable: true
country:
$ref: '#/components/schemas/JobCountry'
salary:
type: string
nullable: true
description:
$ref: '#/components/schemas/JobDescription'
category:
$ref: '#/components/schemas/JobCategory'
type:
$ref: '#/components/schemas/JobType'
experience:
$ref: '#/components/schemas/JobExperience'
language:
$ref: '#/components/schemas/JobLanguage'
published_date:
type: string
description: >-
The date the job was last published. This will be `null` if the job
was never published.
format: date-time
created_date:
type: string
description: The date the job was created.
format: date-time
hosted_url:
type: string
nullable: true
compensation_tiers:
type: array
items:
$ref: '#/components/schemas/CompensationTier'
nullable: true
additionalProperties: false
JobCountry:
type: object
properties:
name:
type: string
nullable: true
code:
type: string
nullable: true
additionalProperties: false
JobDescription:
type: object
properties:
html:
type: string
nullable: true
text:
type: string
nullable: true
additionalProperties: false
JobCategory:
type: object
properties:
id:
type: integer
description: The id of the category, format `cat_abc123`.
format: int32
name:
type: string
nullable: true
additionalProperties: false
JobType:
type: object
properties:
type:
type: string
nullable: true
name:
type: string
nullable: true
additionalProperties: false
JobExperience:
type: object
properties:
type:
type: string
nullable: true
name:
type: string
nullable: true
additionalProperties: false
JobLanguage:
type: object
properties:
name:
type: string
nullable: true
code:
type: string
nullable: true
additionalProperties: false
CompensationTier:
type: object
properties:
label:
maxLength: 1000
type: string
nullable: true
type:
$ref: '#/components/schemas/CompensationType'
interval:
$ref: '#/components/schemas/CompensationInterval'
currency_code:
maxLength: 3
type: string
nullable: true
currency_symbol:
type: string
nullable: true
readOnly: true
min_value:
type: number
format: double
nullable: true
max_value:
type: number
format: double
nullable: true
information:
maxLength: 1000
type: string
nullable: true
additionalProperties: false
CompensationType:
enum:
- none
- fixed_salary
- range_salary
type: string
CompensationInterval:
enum:
- none
- hour
- day
- week
- month
- year
type: string
````