Export Jobs

Export job search results using the same search parameters as /v2/jobs/search, but save the result as a downloadable file. This endpoint creates a task and returns its status and identifier. The user can poll the task using the Get Task Status endpoint.

This endpoint requires an API key for all requests. See Authentication to get one.

Endpoint

POST /v2/jobs/export

Authentication

x-api-key

string

required

Your Hirebase API key

Request Body

Use job_types (plural) — job_type (singular) is silently ignored and your filter will not apply.

Note:

While some top-level request fields are required (such as search), the attributes within those fields are optional. You can include only the filters you need, for example, specifying just job_titles inside search is valid.
Filter combinations can be mixed and matched.
Use specific filters to narrow down search results and get relevant matches.

object

Parameters used to filter job search results

Show child attributes

job_titles

string[]

Array of job titles to search for.

keywords

string[]

Array of keywords to match in job descriptions

job_board

string

Filter by the source job board (e.g., “iCIMS”, “Lever”, “Greenhouse”).

job_slug

string

Filter by the unique job slug (used for deep linking or targeting specific jobs).

location_group

string

Predefined geographic area (e.g., “Bay_Area”)

location_types

string[]

Array of work arrangements. Accepted values: "Remote", "Hybrid", "In-Person".

locations

object[]

Array of structured location objects with city, region, and country.

Show child attributes

city

string

City name

region

string

State, region, or province

country

string

Country name

experience

string[]

Array of experience levels. Accepted values: "Entry", "Junior", "Mid", "Senior", "Executive".

yoe

object

Years of experience range object.

Show child attributes

min

number

Minimum years of experience

max

number

Maximum years of experience

company_name

string

Filter by specific company name

company_slug

string

Filter by the unique company slug (used for deep linking or specific company targeting).

salary

object

Salary range object.

Show child attributes

min

number

Minimum salary

max

number

Maximum salary

job_types

string[]

Array of job types (e.g., "Full Time", "Part Time", "Contract", "Internship").

The correct field name is job_types (plural). job_type is silently ignored.

job_category

string[]

Filter by one or more job category tags (e.g., "Engineering Jobs", "Marketing Jobs").

company_types

string[]

Filter jobs by the hiring company’s headcount bucket. Accepted values: "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10000+". Pass multiple values to combine ranges (e.g., ["11-50", "51-200"]).

This parameter is named company_types for historical reasons but currently filters by company size. A separate classification filter (Public Company / Non-Profit / etc.) will be added in a future API update.

industry

string[]

Filter by industry sector. Can be a single string or an array of strings. See List Industries for accepted values.

sub_industry

string[]

Filter by more specific subindustry category. Can be a single string or an array of strings. See List Subindustries for accepted values.

date_posted

string

The date when the job was posted. Format: YYYY-MM-DD

visa

string

Filter for jobs that offer visa sponsorship (“true” or “false”)

sort_by

string

Field to sort results by. Accepted values: "relevance", "date_posted", "salary", "company", "yoe". Invalid values are silently ignored.

sort_order

string

Sort direction ("asc" or "desc").

currency

string

Currency code for salary filtering (e.g., “USD”, “EUR”).

days_ago

number

Filter jobs posted within the last specified number of days.

include_expired

string

Whether to include expired job listings in the results (“true” or “false”).

include_no_salary

string

Whether to include jobs that do not specify a salary (“true” or “false”).

include_yoe

string

Whether to include jobs without explicit years of experience data (“true” or “false”).

month

string

Filter jobs posted in a specific month. Format: YYYY-MM (e.g., “2024-06”).

page

number

default:"1"

Page number for pagination

limit

number

default:"10"

Number of results per page

Note:The pagination (page and limit) fields control the number of results returned and which subset of results is displayed.

format

string

required

Export file format (csv, or json)

Differences from /v2/jobs/search: The search object accepts most of the same filters as Search Jobs, but a few POST-only conveniences (e.g., return_raw_description, hide_recruiting_agencies) are not applied by the export pipeline. Pagination fields (page, limit) are accepted but the export will process the entire matching result set, not just a single page.

Rate limit: 4 requests/second on search endpoints (including export). See Error Handling.

Response

Returns a task object representing the export job.

Asynchronous workflow: This endpoint returns immediately with a task object. Use the returned id to poll GET /v2/tasks/{task_id}. When state becomes "completed", the result.download_url field will contain the URL to fetch your exported file.Heads-up: The export processes the entire matching result set. limit and page in the search body are ignored — all matching jobs are exported.

string

Unique task ID

Note:Use this task ID to check the export status using the Get Task Status endpoint and download the result once it’s ready.

type

string

Type of the task, always "export_job_data" for this endpoint

state

string

Current state of the task (queued, processing, completed, failed)

progress

number

Task progress as a float between 0.0 and 1.0

created_at

string

ISO timestamp of task creation

updated_at

string

ISO timestamp of last update

started_at

string

ISO timestamp of when the task started, or null

completed_at

string

ISO timestamp of when the task completed, or null

user_id

string

ID of the user who initiated the task

error

string

Error message if the task failed, otherwise null

worker_id

string

ID of the worker that processed the task, or null

priority

integer

Task priority level (higher means more urgent)

input

object

Task input payload, including the search query and export format

result

object

Present only when the task is complete

Show child attributes

download_url

string

URL to download the exported file

file_size

integer

File size in bytes

record_count

integer

Total number of jobs exported

expiry_time

string

ISO timestamp when the download URL will expire

format

string

Format of the exported file (e.g., json, csv).

Example Request

{
    "search": {
  "job_titles": ["Site/Civil Engineer"],
  "geo_locations": [{"city": "Richmond", "region": "Virginia", "country": "United States"}],
  "yoe": {"min": 1, "max": 6},
  "company_name": "CompanyXYZ",
  "job_types": ["Full Time"],
  "industry": ["Design", "Construction"],
  "sub_industry": ["Architecture", "Building Construction"],
  "visa": "true",
  "sort_by": "relevance",
  "sort_order": "desc",
  "page": 1,
  "limit": 10
},
  "format": "json"
}

Example Response

{
    "id": "7700n868-05b7-4763-af74-e2c789c3260d",
    "type": "export_job_data",
    "state": "queued",
    "progress": 0.0,
    "created_at": "2025-06-13T06:10:07.605259",
    "updated_at": "2025-06-13T06:10:07.605260",
    "started_at": null,
    "completed_at": null,
    "user_id": "27893d278da3e42f2878gh90",
    "error": null,
    "worker_id": null,
    "priority": 0,
    "input": {
        "query": {
            "job_titles": [
                "Site/Civil Engineer"
            ],
            "keywords": null,
            "location_group": null,
            "location_types": [
                "In-Person"
            ],
            "geo_locations": [
                {
                    "city": "Richmond",
                    "region": "Virginia",
                    "country": "United States"
                }
            ],
            "experience": null,
            "yoe": {
                "min": 1.0,
                "max": 6.0
            },
            "include_yoe": null,
            "company_types": null,
            "company_name": "CompanyXYZ",
            "date_posted": null,
            "days_ago": null,
            "month": null,
            "salary": null,
            "include_no_salary": null,
            "currency": null,
            "job_types": [
                "Full Time"
            ],
            "job_category": null,
            "industry": [
                "Design",
                "Construction"
            ],
            "sub_industry": [
                "Architecture",
                "Building Construction"
            ],
            "visa": "false",
            "include_expired": null,
            "hide_seen_jobs": null,
            "user_id": null,
            "company_slug": null,
            "job_slug": null,
            "job_board": null,
            "sort_by": "relevance",
            "sort_order": "desc",
            "page": 1,
            "limit": 10
        },
        "format": "json"
    },
    "result": null
}

Error Responses

401 Unauthorized

Returns when the API key is missing, invalid, or incorrect.

403 Forbidden

Returns when your account does not have permission to access the requested feature.

This usually means the feature is restricted to certain subscription tiers.

422 Unprocessable Entity Error

Returns when the request contains invalid or improperly formatted data.

Occurs when the industry field is missing, not a string, or doesn’t match any value from the list of valid industries.
Can also be returned if sub_industry is not a valid string from the list of allowed sub-industries.
May result from JSON decoding errors, such as malformed JSON or incorrect data types in the request body.

500 Internal Server Error

Returns when an unexpected error occurs on the server.

Also occurs during unhandled server-side failures or bugs that prevent the request from being processed.

Jobs API

Companies API

Reference Data API

Resume (Embeddings) API

Tasks API

Error Handling

Endpoint

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Jobs API

Companies API

Reference Data API

Resume (Embeddings) API

Tasks API

Error Handling

Documentation Index

​Endpoint

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

Endpoint

Authentication

Request Body

Response

Example Request

Example Response

Error Responses