Skip to main content
Hirebase exposes several endpoints that overlap in what they return — jobs, companies, search results — but they’re tuned for very different use cases. This guide walks through the most common things people build on top of Hirebase and which API to reach for.

​
Quick Decision Guide

Add job search to your app

Use POST /v2/jobs/search

Build your own product on Hirebase data

Use POST /v2/jobs/export — sync to your own database

Show 'similar jobs' under a listing

Use POST /v2/jobs/neural-search with vector.job_ids

Match jobs to a candidate's resume

Use POST /v2/resumes/embed → POST /v2/jobs/neural-search with vector.vectors

Build company profile pages

Use POST /v2/hirebase/companies/search + GET /v2/hirebase/companies/{slug}

Keep your local data fresh

Use GET /v2/jobs/expired-jobs on a schedule

​
1. Adding Job Search to an Existing App

Use: POST /v2/jobs/search This is the right starting point for most integrations: a job board, a careers page, a search bar in a community app, an internal tool — anywhere you want users to type a query and see a paginated list of matching jobs back. It’s the simplest endpoint to integrate, the response shape is predictable, and every job comes back with a unique job_slug and company_slug you can use to build clean URLs in your own app:
You don’t need to store anything on your side — Hirebase is the source of truth. Just call the search endpoint when the user submits a query, render the results, and link the slugs to a detail page that calls GET /v2/jobs/{job_id} for the full record.
Every request needs an API key, but the Free plan includes 500 jobs a month at no cost, so you can prototype the search box before you pay.

​
When this stops being the right choice

The /jobs/search endpoint is paginated. As long as your users are searching — narrowing a filter, looking at the first few pages of relevant jobs — pagination is fine and you’ll never feel a slowdown. Where it breaks down is when you try to use the search endpoint to iterate over the entire dataset. Past roughly 200,000 results, deep pagination gets noticeably slow. If you find yourself writing a loop that keeps incrementing page to walk every job in the database, you’ve outgrown this endpoint — see the next section.

​
2. Building Your Own Product on Hirebase Data

Use: POST /v2/jobs/export If you’re building a real product on top of Hirebase data — your own search engine, an analytics dashboard, an ATS feature, an LLM agent that needs offline access to job listings — don’t paginate the search endpoint. Use the export API instead. POST /v2/jobs/export takes the same filter shape as /jobs/search but kicks off an async task that produces a CSV or JSON file. The export returns at most limit records (default 10) — to back-fill a dataset, pass a large limit (e.g. the total_count from /jobs/search for the same filters), or paginate with page + limit. You then poll GET /v2/tasks/{task_id} until state is "finished", download the file from result.download_url, and load it into your own database (Postgres, ElasticSearch, MongoDB — whatever fits your stack).
After your initial backfill, run smaller incremental exports on a schedule (e.g., daily with days_ago: 1) to pick up new listings, and use Expired Jobs to remove stale ones (see section 6).
The export returns at most limit records (default 10). Set limit high to export your full result set (e.g. the total_count from /jobs/search for the same filters), or paginate with page + limit.

​
3. Similar Jobs / Recommendations

Use: POST /v2/jobs/neural-search with vector.job_ids If you have a job detail page and want a “Similar jobs” rail at the bottom, pass the _id of the job the user is looking at in vector.job_ids. Hirebase uses that job’s embedding as the query and returns the most semantically similar listings. Add lexical filters to keep the rail relevant (same location type, same country, exclude expired):
Results are ranked by semantic similarity. A per-job vector_score field is not currently returned on this endpoint. The same endpoint with vector.query powers a natural-language search bar — useful if you want users to type “remote backend role at a Series B fintech with equity” instead of clicking filters.

​
4. Resume-to-Jobs Matching

If your product takes a candidate’s resume (PDF, DOCX, etc.) and recommends jobs, there are two supported paths. Pick based on whether you want the resume stored.

​
Path A — Stored (reusable artifact_id)

Use: POST /v2/resumes/upload/ → POST /v2/resumes/{id}/parse → POST /v2/jobs/neural-search. Best when you’ll re-query the same candidate repeatedly.
  1. Upload the resume to /v2/resumes/upload/. You get back an _id (a MongoDB ObjectId) that doubles as the artifact_id.
  2. Parse it via /v2/resumes/{id}/parse to populate structured fields.
  3. Match jobs with artifact_id:

​
Path B — Stateless (nothing stored)

Use: POST /v2/resumes/embed → POST /v2/jobs/neural-search with vector.vectors. Best when you don’t want the resume stored server-side.
  1. Embed the resume at /v2/resumes/embed. You get back parsed structured data plus a 768-dimensional embedding (no stored id).
  2. Pass the embedding into /v2/jobs/neural-search as vector.vectors: [<embedding>].

​
5. Company Profiles and Sales Prospecting

Use: POST /v2/hirebase/companies/search + GET /v2/hirebase/companies/{company_slug} If you’re building company profile pages, a “companies hiring now” directory, or a sales prospecting tool that targets companies with active job openings, the company endpoints are the right place to start. A common pattern: search for companies matching your ICP (e.g., Series A–C fintech in the US), then for each result pull their open roles to see what they’re hiring for and at what scale. The job count is a strong signal of growth.

​
6. Keeping a Synced Database Fresh

Use: GET /v2/jobs/expired-jobs on a schedule If you’ve taken the export route and have a local copy of Hirebase data, you need two things to keep it fresh:
  1. New jobs — run a small daily export with days_ago: 1 and upsert into your DB.
  2. Removed jobs — call /v2/jobs/expired-jobs?since=<yesterday> daily, and mark the returned (company_slug, job_slug) pairs as expired in your DB.
The expired feed and its export only go back 14 days. After a longer outage, re-export live jobs and remove any you hold that are not in the new export. This pair of jobs (export for new, expired-jobs for removed) is enough to keep a local mirror within ~24 hours of the live source.

​
Combining Endpoints

Most real products use more than one endpoint. A typical job-board build looks like:
  1. Search — POST /v2/jobs/search powers the search bar.
  2. Detail — GET /v2/jobs/{job_id} powers the job detail page.
  3. Similar — POST /v2/jobs/neural-search (with vector.job_ids) powers the “Similar jobs” rail at the bottom.
  4. Company — GET /v2/hirebase/companies/{slug} powers the company sidebar.
A typical recommendations product looks like:
  1. Embed — POST /v2/resumes/embed per user when they sign up.
  2. Match — POST /v2/jobs/neural-search with vector.vectors from the embed response on a schedule to surface new matches.
A typical analytics or LLM-agent product looks like:
  1. Backfill — one big POST /v2/jobs/export to seed your DB.
  2. Daily delta — small export + expired-jobs calls on a cron.
  3. Query locally — once the data is yours, you can index, embed, and serve it however you want.

​
Still not sure?

Pick /v2/jobs/search and start prototyping. If you find yourself paginating past page ~2,000, switch to /v2/jobs/export. If you find yourself running the same query repeatedly to refresh data, switch to /v2/jobs/export + /v2/jobs/expired-jobs on a schedule. If users are typing natural-language queries instead of clicking filters, add /v2/jobs/neural-search. Email spencer@hirebase.org if you want a sanity check on which endpoint fits — happy to talk through a specific use case.