JobSphere API Documentation

Welcome to the JobSphere API. This documentation covers everything you need to integrate with our job board platform. The API is designed to be simple, consistent, and RESTful.

Base URL: https://api.jobsphere.io/v1
All requests must be made over HTTPS. Calls made over plain HTTP will fail.

Quick Start

Get up and running in minutes. Install the official SDK or use your preferred HTTP client.

bash 
# Install via npm
npm install @jobsphere/sdk

# Or via pip
pip install jobsphere-python

Authentication

JobSphere uses API keys to authenticate requests. You can view and manage your API keys in the dashboard. All API keys are tied to a specific organization.

Include your API key in the Authorization header as a Bearer token:

http 
GET /v1/jobs HTTP/1.1
Host: api.jobsphere.io
Authorization: Bearer jk_live_sk_a1b2c3d4e5f6...
Security Note: Never expose your secret keys in client-side code or public repositories. Use restricted keys for frontend applications.

Rate Limits

To ensure fair usage, the API enforces rate limits based on your subscription tier:

  • Free Tier: 100 requests/minute
  • Pro Tier: 1,000 requests/minute
  • Enterprise: Custom limits (up to 10k/min)

Rate limit headers are included in every response:

http 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 942
X-RateLimit-Reset: 1698765432

Jobs API

Manage job postings, search listings, and filter by location, salary, or tags.

List Jobs

GET /v1/jobs

Returns a paginated list of active job listings. Supports filtering and sorting.

javascript 
const response = await jobsphere.jobs.list({
  location: "Remote",
  tags: ["react", "node"],
  page: 1,
  per_page: 20
});

Create Job

POST /v1/jobs

Publishes a new job listing. Requires write:jobs scope.

json 
{
  "title": "Senior Frontend Engineer",
  "company": "JobSphere Inc.",
  "location": "San Francisco, CA",
  "type": "full-time",
  "salary_range": {
    "min": 140000,
    "max": 185000,
    "currency": "USD"
  },
  "description": "Join our team to build..."
}

Webhooks

Receive real-time notifications when candidates apply, jobs are published, or applications are updated. Configure webhook endpoints in your dashboard settings.

Webhook payloads are signed using HMAC-SHA256. Verify the signature using the X-JobSphere-Signature header.
javascript 
const verify = await jobsphere.webhooks.verify(
  payload,
  signature,
  webhookSecret
);
if (!verify) throw new Error("Invalid signature");

Error Handling

JobSphere uses conventional HTTP status codes to indicate success or failure:

  • 2xx: Success
  • 4xx: Client error (invalid request, missing permissions)
  • 5xx: Server error (transient failures, retry with exponential backoff)

Error responses include a JSON body with details:

json 
{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: title",
    "details": {
      "field": "title",
      "reason": "cannot be empty"
    }
  }
}

SDKs & Libraries

Official client libraries are available for popular languages and frameworks:

  • JavaScript/TypeScript: @jobsphere/sdk
  • Python: jobsphere-python
  • Go: github.com/jobsphere/go-sdk
  • Ruby: jobsphere-ruby
  • PHP: jobsphere/php
For framework-specific integrations (React, Next.js, Django, Laravel), check the Integrations Guide.