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/vsearch with search_type: "job"

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.
Page 1 is free without an API key, so you can prototype the search box before you sign up. Paginating past page 1 requires a key.

​
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/vsearch with search_type: "job" If you have a job detail page and want a “Similar jobs” rail at the bottom, vector search is built for this. Pass the _id of the job the user is looking at, and Hirebase returns the most semantically similar listings:
Results are ranked by semantic similarity. A per-job score field is not currently returned on this endpoint. The same endpoint with search_type: "summary" 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/vsearch (or 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=YYYY-MM-DD daily, and mark the returned (company_slug, job_slug) pairs as expired in your DB.
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/vsearch (with search_type: "job") 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/vsearch. Email spencer@hirebase.org if you want a sanity check on which endpoint fits — happy to talk through a specific use case.