The Jobs endpoint lets you search and retrieve job listings with powerful filtering options.

List Jobs

GET /v1/public/jobs

Returns a paginated list of jobs matching your filters.

curl -H "X-API-Key: $JOBVEN_API_KEY" \
  "https://api.jobven.com/v1/public/jobs?skills%5B%5D=react&remoteType%5B%5D=remote&limit=20"

const params = new URLSearchParams({ limit: '20' });
params.append('skills[]', 'react');
params.append('remoteType[]', 'remote');

const response = await fetch(
  `https://api.jobven.com/v1/public/jobs?${params}`,
  { headers: { 'X-API-Key': process.env.JOBVEN_API_KEY } }
);
const { data, meta } = await response.json();

import requests
import os

response = requests.get(
    'https://api.jobven.com/v1/public/jobs',
    headers={'X-API-Key': os.environ['JOBVEN_API_KEY']},
    params={'skills[]': 'react', 'remoteType[]': 'remote', 'limit': 20}
)
data = response.json()

Query Parameters

Array Parameters

To filter by several values, repeat the parameter, with or without brackets. One value works either way (skills=react or skills[]=react):

GET /v1/public/jobs?skills[]=react&skills[]=typescript&remoteType[]=remote&remoteType[]=hybrid

Searching

Two parameters search text. Everything each one supports:

q examples:

Both can be combined with each other and with every other filter:

GET /v1/public/jobs?q=backend%20engineer&descriptionQuery=distributed%20systems&postedAfter=1789000000

URL-encode values. A bare + in a query string means a space, so send c++ as descriptionQuery=c%2B%2B.

If a search takes too long to run, the API returns 422 Unprocessable Entity with a message asking you to narrow it. Add postedAfter, or make q or descriptionQuery more specific, and try again.

Description Formats

Job descriptions are stored as sanitized HTML. Use descriptionFormat to request the format your pipeline needs: HTML, plain text, markdown, or all three. All formats are precomputed at ingest time, so responses stay fast even when you request all.

When you request plain or markdown, the HTML description field is omitted, so you only get the format you asked for. all returns every format.

GET /v1/public/jobs?descriptionFormat=markdown

What the HTML contains

The description HTML is structural: paragraphs, headings, lists, tables, emphasis and links. Everything the source site added for its own rendering is removed: scripts, styles, media, form controls, comments, framework attributes, and empty elements. The only attributes kept are href and title on links (an href must be http, https or mailto), and colspan, rowspan and start where they carry structure. Entities are encoded (&,  ).

Links carry no target or rel, so they open in the same tab unless you decide otherwise. To open every link in a new tab, add the attributes when you render:

container.querySelectorAll('a').forEach((a) => {
  a.target = '_blank';
  a.rel = 'noopener';
});

If you sanitize the HTML before rendering (DOMPurify, sanitize-html), do this in a post-sanitize hook, because most sanitizers strip target by default.

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Senior React Developer",
      "descriptionMarkdown": "## About the role\n\nWe are looking for...\n\n- 5+ years React\n- TypeScript fluency"
    }
  ]
}

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Senior React Developer",
      "description": "<p>We are looking for...</p>",
      "summary": "Build modern web applications with React",
      "locations": [
        {
          "addressLocality": "San Francisco",
          "addressRegion": "California",
          "addressCountry": "US",
          "workLocation": "hybrid"
        }
      ],
      "remoteType": "hybrid",
      "skills": {
        "primarySkills": ["React", "TypeScript"],
        "secondarySkills": ["Node.js", "PostgreSQL"],
        "softSkills": ["Communication", "Teamwork"]
      },
      "salary": {
        "min": 150000,
        "max": 200000,
        "currency": "USD",
        "period": "annual",
        "annualMin": 150000,
        "annualMax": 200000
      },
      "benefits": ["health_insurance", "pensions_401k", "remote_work_hybrid_work_options"],
      "experienceLevel": "senior",
      "employmentType": "full_time",
      "minYearsExperience": 5,
      "educationRequirement": {
        "required": ["Bachelor's degree"],
        "preferred": ["Master's degree"]
      },
      "industry": ["technology_software"],
      "inLanguage": ["en"],
      "hasVisaSponsorship": true,
      "hasRelocation": false,
      "requiresTravel": false,
      "postedAt": 1705392000,
      "expiresAt": 1708070400,
      "applyUrl": "https://company.com/apply/123",
      "status": "active",
      "companies": [
        {
          "id": 1042,
          "name": "TechCorp Inc.",
          "website": "https://techcorp.com"
        }
      ]
    }
  ],
  "meta": {
    "count": 20,
    "nextCursor": "eyJpZCI6IjEyMyIsInZhbHVlIjoxNzA1MzkyMDAwMDAwfQ==",
    "hasMore": true,
    "requestTimeMs": 45,
    "lastUpdatedAt": "2025-01-15T12:00:00Z"
  }
}

Response Fields

Location Object

Getting a total count

meta.total is not returned by default. Pass includeTotal=true when you need it:

GET /v1/public/jobs?country=US&includeTotal=true

Counting every matching job is the slowest part of a request, and it gets slower as the dataset grows, so it is opt-in rather than a cost every caller pays. Most integrations never need it: to page through results you use hasMore and nextCursor, and to show progress you count what you have received.

When you do request it, the number is exact for your filters, and may be up to five minutes old. If counting takes too long, meta.total is left out and you still get the page.

Meta Object

Handling Null Values

Most job fields are optional and may be null. Guaranteed fields: id, title, status, companies, and the description field matching your requested format: description when descriptionFormat=html (default) or all, descriptionPlain when plain, descriptionMarkdown when markdown.

// Safe access pattern
const salary = job.salary?.min
  ? `${job.salary.min.toLocaleString()} ${job.salary.currency ?? ''}+`
  : 'Not specified';

const skills = job.skills?.primarySkills?.join(', ') || 'Not listed';

See Data Types - Handling Null Values for complete guidance.

Get Job by ID

GET /v1/public/jobs/{id}

Retrieve a single job by its UUID.

curl -H "X-API-Key: $JOBVEN_API_KEY" \
  "https://api.jobven.com/v1/public/jobs/550e8400-e29b-41d4-a716-446655440000"

const response = await fetch(
  'https://api.jobven.com/v1/public/jobs/550e8400-e29b-41d4-a716-446655440000',
  { headers: { 'X-API-Key': process.env.JOBVEN_API_KEY } }
);
const job = await response.json();

response = requests.get(
    'https://api.jobven.com/v1/public/jobs/550e8400-e29b-41d4-a716-446655440000',
    headers={'X-API-Key': os.environ['JOBVEN_API_KEY']}
)
job = response.json()

Path Parameters

Response

Returns a single job object (same schema as list response items).

Errors

Pagination

Jobs use cursor-based pagination for efficient traversal of large datasets.

How It Works

1. Make your first request without a cursor
2. Use meta.nextCursor from the response for the next page
3. Continue until meta.hasMore is false
4. Keep every other parameter the same between pages: filters, sortBy and order. A cursor marks a position in one listing.

let cursor = null;
const allJobs = [];

do {
  const url = new URL('https://api.jobven.com/v1/public/jobs');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const response = await fetch(url, {
    headers: { 'X-API-Key': process.env.JOBVEN_API_KEY }
  });
  const { data, meta } = await response.json();

  allJobs.push(...data);
  cursor = meta.nextCursor;
} while (cursor);

console.log(`Fetched ${allJobs.length} jobs`);

A cursor that can't be decoded returns 400. Start the walk again without one.

Page Size Limits

A limit above your tier's maximum is clamped to it, not rejected. A limit of 0 or below, or a non-integer, returns 400.

See also

• Webhooks: push the same job lifecycle events (job.created, job.updated, job.closed, job.deleted) to your endpoint in real time instead of polling.