JobSphere SDK

Official client libraries for integrating JobSphere's job board API into your applications. Fetch listings, submit applications, and manage employer accounts programmatically.

Installation

Choose your preferred language and install the SDK via your package manager:

npm / yarn / pnpm 
# Using npm
npm install @jobsphere/sdk

# Using yarn
yarn add @jobsphere/sdk

# Using pnpm
pnpm add @jobsphere/sdk
Requirements: Node.js 18+, Python 3.9+, or PHP 8.1+. TypeScript types are included in the JS package.

Authentication

The SDK uses API keys for authentication. You can generate keys from the JobSphere Developer Dashboard. Keys are scoped by role: read, write, or admin.

client.js 
import { JobSphere } from '@jobsphere/sdk';

const client = new JobSphere({
  apiKey: 'js_live_sk_8f7a6b5c4d3e2f1g0h9i',
  environment: 'production' // or 'sandbox'});

// Verify connection
const status = await client.health();
console.log(status.message); // "API connection successful"
Security Note: Never commit API keys to version control. Use environment variables or secret managers.

Quick Start

Fetch and paginate through job listings in under 10 lines of code:

search.js 
const results = await client.jobs.search({
  query: 'frontend engineer',
  location: 'remote',
  filters: { salary_min: 90000, posted_within: '7d' },
  limit: 10
});

console.log(`Found ${results.total} jobs`);
results.jobs.forEach(job => {
  console.log(`- ${job.title} @ ${job.company.name}`);
});

Core Methods

Jobs & Listings

Method Description Scope
jobs.search(params) Full-text search with pagination read
jobs.get(id) Fetch complete job details read
jobs.publish(payload) Create or update a listing write
jobs.archive(id) Remove active listing admin

Applications

Submit candidate applications programmatically. Supports PDF resumes and JSON payloads.

apply.js 
const application = await client.applications.submit({
  job_id: 'job_9x8y7z',
  candidate: {
    name: 'Alex Chen',
    email: 'alex@example.com',
    resume_url: 'https://cdn.example.com/resume.pdf'
  },
  message: 'Interested in this role. Portfolio linked.'
});
// Returns application tracking ID & status

Rate Limits & Performance

API limits are enforced per API key, not per IP address:

  • Read endpoints: 1,200 requests / minute
  • Write endpoints: 200 requests / minute
  • Bulk operations: Max 500 items per batch

When limits are reached, the SDK automatically retries with exponential backoff. Override default behavior:

config.js 
const client = new JobSphere({
  apiKey: process.env.JOBSPHERE_API_KEY,
  retries: 3,
  timeout: 5000, // ms
  onRateLimit: (retryAfter) => {
    console.warn(`Rate limited. Retry in ${retryAfter}s`);
  }
});

Error Handling

The SDK throws standardized error objects. Catch and inspect the code and message properties:

errors.js 
try {
  await client.jobs.publish(payload);
} catch (err) {
  if (err instanceof JobSphere.errors.ValidationError) {
    console.error('Invalid payload:', err.details);
  } else {
    console.error('API Error', err.code, err.message);
  }
}

Support & Community

Need help integrating the SDK? Reach out through any of these channels:

Report bugs, request features, or contribute to the open-source SDK repositories.