Quick Start

Make your first Jobven API call in under 5 minutes. Step-by-step tutorial for fetching job listings.

This guide will walk you through making your first Jobven API call. By the end, you'll have successfully fetched job listings and understand the response format.

Want to see the response shape before you get a key? This is a live record from the API:

See real data

The newest job in the index, straight from the live API. No signup.

Prerequisites

Before starting, make sure you have:

✅ A Jobven account
✅ An API key from your dashboard
✅ A tool to make HTTP requests (cURL, Postman, or your preferred language)

Step 1: Make Your First Request

Let's start with a simple request to list jobs. Replace your_api_key with your actual API key:

curl -X GET 'https://api.jobven.com/v1/public/jobs?limit=5' \
  -H 'X-API-Key: your_api_key'

const response = await fetch(
  'https://api.jobven.com/v1/public/jobs?limit=5',
  {
    headers: {
      'X-API-Key': 'your_api_key'
    }
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.jobven.com/v1/public/jobs',
    headers={'X-API-Key': 'your_api_key'},
    params={'limit': 5}
)

data = response.json()
print(data)

Step 2: Understand the Response

A successful response looks like this:

{
  "data": [
    {
      "id": "abc123-def456-ghi789",
      "title": "Senior Software Engineer",
      "description": "We are looking for an experienced software engineer...",
      "summary": "Build scalable systems for a growing fintech company",
      "locations": [
        {
          "addressLocality": "San Francisco",
          "addressRegion": "California",
          "addressCountry": "US",
          "workLocation": "hybrid"
        }
      ],
      "remoteType": "hybrid",
      "skills": {
        "primary_skills": ["Python", "PostgreSQL", "AWS"],
        "secondary_skills": ["Docker", "Kubernetes"],
        "soft_skills": ["communication", "leadership"]
      },
      "salary": {
        "min": 150000,
        "max": 200000,
        "currency": "USD",
        "period": "annual"
      },
      "experienceLevel": "senior",
      "employmentType": "full_time",
      "companies": [
        {
          "name": "Example Corp",
          "website": "example.com"
        }
      ],
      "postedAt": 1705392000,
      "status": "active"
    }
  ],
  "meta": {
    "count": 5,
    "nextCursor": "eyJpZCI6ImFiYzEyMyIsInZhbHVlIjoxNzA1MzkyMDAwMDAwfQ==",
    "hasMore": true,
    "requestTimeMs": 45,
    "lastUpdatedAt": "2025-01-20T12:00:00Z"
  }
}

Response Structure

Field	Description
`data`	Array of job objects matching your query
`meta.total`	Exact number of jobs matching your filters. Only returned when you pass `includeTotal=true`
`meta.count`	Number of jobs in this response
`meta.nextCursor`	Cursor for fetching the next page
`meta.hasMore`	Whether more results exist
`meta.requestTimeMs`	API response time in milliseconds
`meta.lastUpdatedAt`	Timestamp of most recently updated job

Step 3: Add Filters

Now let's search for specific jobs. Here's how to find remote software engineering positions:

curl -X GET 'https://api.jobven.com/v1/public/jobs?q=software%20engineer&remoteType[]=remote&limit=10' \
  -H 'X-API-Key: your_api_key'

const params = new URLSearchParams({
  q: 'software engineer',
  'remoteType[]': 'remote',
  limit: 10
});

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

const data = await response.json();
console.log(`Found ${data.data.length} remote software engineering jobs`);

import requests

response = requests.get(
    'https://api.jobven.com/v1/public/jobs',
    headers={'X-API-Key': 'your_api_key'},
    params={
        'q': 'software engineer',
        'remoteType[]': 'remote',
        'limit': 10
    }
)

data = response.json()
print(f"Found {len(data['data'])} remote software engineering jobs")

Common Filters

Filter	Example	Description
`q`	`?q=developer`	Search in title, summary, description
`skills[]`	`?skills[]=python&skills[]=react`	Filter by required skills
`remoteType[]`	`?remoteType[]=remote`	On-site, remote, hybrid, flexible
`location`	`?location=New York`	Filter by location name
`country`	`?country=US`	Filter by country code
`experienceLevel`	`?experienceLevel=senior`	Entry, mid, senior, lead, executive
`minSalary`	`?minSalary=100000`	Minimum salary filter

See the Jobs Reference for all available filters.

Step 4: Get a Single Job

To fetch detailed information about a specific job, use its ID:

curl -X GET 'https://api.jobven.com/v1/public/jobs/abc123-def456-ghi789' \
  -H 'X-API-Key: your_api_key'

const jobId = 'abc123-def456-ghi789';

const response = await fetch(
  `https://api.jobven.com/v1/public/jobs/${jobId}`,
  {
    headers: {
      'X-API-Key': 'your_api_key'
    }
  }
);

const job = await response.json();
console.log(job.title, 'at', job.companies[0].name);

import requests

job_id = 'abc123-def456-ghi789'

response = requests.get(
    f'https://api.jobven.com/v1/public/jobs/{job_id}',
    headers={'X-API-Key': 'your_api_key'}
)

job = response.json()
print(f"{job['title']} at {job['companies'][0]['name']}")

Step 5: Paginate Through Results

For large result sets, use cursor pagination to fetch all jobs:

async function getAllJobs(query) {
  const allJobs = [];
  let cursor = null;
  let hasMore = true;

  while (hasMore) {
    const params = new URLSearchParams({
      q: query,
      limit: 100,
      ...(cursor && { cursor })
    });

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

    const data = await response.json();
    allJobs.push(...data.data);

    cursor = data.meta.nextCursor;
    hasMore = data.meta.hasMore;

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

  return allJobs;
}

// Usage
const jobs = await getAllJobs('developer');
console.log(`Total jobs fetched: ${jobs.length}`);

import requests

def get_all_jobs(query):
    all_jobs = []
    cursor = None
    has_more = True

    while has_more:
        params = {'q': query, 'limit': 100}
        if cursor:
            params['cursor'] = cursor

        response = requests.get(
            'https://api.jobven.com/v1/public/jobs',
            headers={'X-API-Key': 'your_api_key'},
            params=params
        )

        data = response.json()
        all_jobs.extend(data['data'])

        cursor = data['meta']['nextCursor']
        has_more = data['meta']['hasMore']

        print(f"Fetched {len(all_jobs)} jobs so far...")

    return all_jobs

# Usage
jobs = get_all_jobs('developer')
print(f"Total jobs fetched: {len(jobs)}")

Tip: For daily updates, use the postedAfter parameter instead of fetching all jobs. This is much more efficient for keeping your data in sync.

Need Help?

If you run into issues:

Check the API Reference for detailed documentation
Review your API key settings and rate limits
Contact support at [email protected]

Authentication

Learn how to authenticate with the Jobven API using API keys. Generate keys from your dashboard and include them in the X-API-Key header.

API Reference

Jobven API reference. Base URL, authentication, response format, and error codes for all endpoints.