JobSphere API Documentation

Integrate our job board platform into your application. Access thousands of jobs, manage applications, and track candidates programmatically.

Base URL: https://api.jobsphere.io/v1
All requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. (unless documented otherwise)

Authentication

JobSphere uses API keys to authenticate requests. You can view and manage your API keys in the dashboard.

API keys can be scoped to Read Only or Read/Write. You must pass your API key in the header of every request:

Header

Authorization: Bearer YOUR_API_KEY_HERE

Security Notice: Never expose your private API keys in client-side code, public repositories, or browser consoles. Use environment variables for server-side implementation.

Jobs API

GET /jobs

Returns a list of job listings. Results are paginated and can be filtered by query, category, location, and experience level.

Query Parameters

Parameter	Type	Description
`q`	string	Search query (title, skills, company)
`category`	string	Job category slug (e.g., `engineering`)
`location`	string	City, country, or `remote`
`limit`optional	integer	Number of results (max 100). Default: 20
`page`optional	integer	Page number for pagination. Default: 1

Example Request

cURL

curl -X GET "https://api.jobsphere.io/v1/jobs?q=react&location=remote&limit=5" \\
  -H "Authorization: Bearer sk_live_abc123..."

Example Response

JSON (200 OK)

{
  "data": [
    {
      "id": "job_8x29a1b3",
      "title": "Senior Frontend Engineer",
      "company": { "id": "comp_123", "name": "TechCorp", "logo_url": "https://..." },
      "location": "Remote",
      "type": "Full-time",
      "salary_range": { "min": 140000, "max": 185000, "currency": "USD" },
      "posted_at": "2025-04-10T08:00:00Z",
      "skills": ["React", "TypeScript", "Next.js"]
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 12,
    "total_items": 234
  }
}

GET /jobs/:id

Retrieves detailed information about a specific job listing, including full description, requirements, and application instructions.

POST /jobs

Creates a new job listing. Requires a Read/Write API key and employer verification.

Body Parameter	Type	Description
`title`required	string	Job title
`company_id`required	string	Your verified company ID
`description`required	string	Markdown supported description
`location`required	string	Location or "Remote"
`tags`optional	array	Array of skill/category tags

Applications API

POST /applications

Submit a job application on behalf of a candidate or through your integrated careers page.

Request Body

{
  "job_id": "job_8x29a1b3",
  "candidate_email": "dev@example.com",
  "resume_url": "https://secure.storage/resume.pdf",
  "cover_letter": "I'm excited to apply for...",
  "source": "api_integration"
}

Error Codes

JobSphere uses standard HTTP status codes to indicate success or failure of requests.

Code	Meaning	Description
`200`	OK	Request successful
`400`	Bad Request	Missing or invalid parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Insufficient permissions for this action
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Something went wrong on our end

Rate Limits

To ensure platform stability, API requests are rate-limited based on your plan tier:

Free Tier: 60 requests / minute
Pro Tier: 500 requests / minute
Enterprise: Custom limits (1000+ / minute)

Rate limit information is included in response headers:

Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1689234567