{
"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"
}
],
"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"
}
}
}
},
"/api/v2/jobs/{jobId}": {
"get": {
"tags": [
"JobsAPIV2"
],
"summary": "Get a job by id",
"parameters": [
{
"name": "job_id",
"in": "query",
"description": "",
"schema": {
"type": "integer",
"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": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JobAPIV2"
}
}
}
},
"404": {
"description": "Job not found or is not published"
}
}
}
},
"/api/v2/jobs/categories": {
"get": {
"tags": [
"JobsAPIV2"
],
"summary": "Gets a list of categories with the published job count in the category",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CategoryGroup"
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"CategoryGroup": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"count": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false
},
"CompensationInterval": {
"enum": [
"none",
"hour",
"day",
"week",
"month",
"year"
],
"type": "string"
},
"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"
},
"EmploymentType": {
"enum": [
"full_time",
"part_time",
"contract",
"temporary",
"other",
"internship",
"volunteer"
],
"type": "string"
},
"Experience": {
"enum": [
"na",
"intern",
"entry_level",
"mid_level",
"senior"
],
"type": "string"
},
"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
},
"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
},
"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
},
"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
},
"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
},
"JobType": {
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
}
},
"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
},
"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
},
"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": { }
}
}
}
}