JobSphere API Documentation

Welcome to the official JobSphere API documentation. The JobSphere REST API allows developers to programmatically access job listings, candidate profiles, company data, and application workflows. This guide covers authentication, endpoints, SDK integration, and best practices.

Base URL: All API requests should be made to https://api.jobsphere.io/v2. Ensure you include the Content-Type: application/json header in all POST/PUT requests.

Authentication

JobSphere uses API keys for authentication. You can generate your keys from the Developer Dashboard. Include your API key in the request header as follows:

HTTP Header

Authorization: Bearer your_api_key_here
Content-Type: application/json

Security Notice: Never expose your API keys in client-side code or public repositories. Use environment variables and server-side proxies for frontend applications.

Jobs Endpoint

Retrieve, create, update, and manage job listings across the JobSphere network.

GET /jobs

Search and paginate through job listings with filters.

POST /jobs

Create a new job posting with detailed specifications.

PUT /jobs/{id}

Update an existing job listing.

DELETE /jobs/{id}

Remove or archive a job listing.

Request Parameters

Parameter	Type	Required	Description
`q`	string	Optional	Search query for job titles, skills, or company names
`location`	string	Optional	Filter by city, state, country, or "remote"
`type`	string	Optional	Job type: `full_time`, `part_time`, `contract`
`page`	integer	Optional	Page number for pagination (default: 1)
`limit`	integer	Optional	Results per page (max: 100, default: 20)

Example Request

cURL

curl -X GET "https://api.jobsphere.io/v2/jobs?q=frontend&location=remote&limit=10" \
  -H "Authorization: Bearer $JS_API_KEY"

Response Example

JSON

{
  "data": [
    {
      "id: "job_8f9a2b3c",
      "title: "Senior Frontend Engineer",
      "company: "JobSphere Inc.",
      "location: "Remote",
      "type: "full_time",
      "salary_range: {
        "min: 120000,
        "max: 180000,
        "currency: "USD"
      },
      "posted_at: "2024-01-15T08:00:00Z"
    }
  ],
  "meta: {
    "total: 142,
    "page: 1,
    "limit: 10
  }
}

Webhooks

Subscribe to real-time events in your JobSphere workspace. When an event occurs, JobSphere sends a POST request to your configured webhook URL.

Event Types

Event	Description
`job.created`	Triggered when a new job is published
`job.updated`	Triggered when job details change
`application.received`	Triggered when a candidate applies
`candidate.status_changed`	Triggered when application status updates

Webhook Security: All webhook payloads are signed using HMAC-SHA256. Verify the X-JobSphere-Signature header before processing events.

SDKs & Libraries

Official JobSphere SDKs are available for popular languages. Each SDK handles authentication, retries, pagination, and type safety automatically.

Node.js

const JobSphere = require('jobsphere-node');

const js = new JobSphere({
  apiKey: process.env.JS_API_KEY
});

const jobs = await js.jobs.list({
  q: 'python',
  location: 'remote',
  limit: 20
});

console.log(jobs.data);

Python

from jobsphere import Client

client = Client(api_key="your_key_here")
jobs = client.jobs.list(q="react", type="full_time")

for job in jobs.items:
    print(job.title, job.location)

Error Handling

JobSphere uses standard HTTP status codes and returns detailed error objects in the response body.

Status	Meaning	Common Causes
`400`	Bad Request	Invalid parameters, malformed JSON
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for the endpoint
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal JobSphere issue

Need Help?

If you encounter issues or have questions about the API, reach out to our developer support team:

Email: developers@jobsphere.io
Community: Join Discord
Changelog: View Updates