API Documentation

Build powerful integrations with JobSphere's RESTful API. Access job listings, manage applications, and sync candidate data programmatically.

All API requests are made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. The API is versioned via the URL path (`/v1/`).

Authentication

JobSphere uses API keys to authenticate requests. You can view and manage your API keys in the developer dashboard. Never share your API keys publicly or commit them to version control.

Include your API key in the Authorization header using Bearer token format:

Authorization: Bearer <YOUR_API_KEY>

For OAuth 2.0 integrations (e.g., social login or third-party apps), exchange your client_id and client_secret at POST /auth/token.

Base URL & Request Format

All API endpoints are relative to:

https://api.jobsphere.com/v1

JobSphere accepts JSON payloads (`application/json`) and returns JSON responses. Standard HTTP methods (GET, POST, PUT, DELETE) are supported. All timestamps are in ISO 8601 format (UTC).

Jobs Endpoints

GET /jobs

Retrieve a paginated list of job postings. Supports filtering by title, location, category, salary, and company.

Parameter	Type	Required	Description
q	string	False	Search query for job title or description
location	string	False	Filter by city, country, or remote
category	string	False	Category slug (e.g., engineering, design)
limit	integer	False	Results per page (max 50, default 20)

Example Response

{
  "data": [
    {
      "id": "job_8f3k29",
      "title": "Senior Frontend Developer",
      "company": { "id": "comp_92x", "name": "TechCorp", "logo_url": "https://cdn.jobsphere.com/logos/techcorp.png" },
      "location": "San Francisco, CA",
      "salary_range": { "min": 120000, "max": 160000, "currency": "USD" },
      "posted_at": "2024-03-15T08:00:00Z"
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 12, "has_more": true }
}

POST /jobs/{id}/apply

Submit a job application on behalf of a candidate. Triggers email notifications to the hiring manager.

Parameter	Type	Required	Description
candidate_email	string	True	Applicant's email address
resume_url	string	True	Public URL to PDF resume
cover_letter	string	False	Optional cover letter text
phone	string	False	Contact phone number

Companies Endpoints

GET /companies/{id}

Fetch detailed information about a specific company, including profile details, open positions count, industry classification, and verified status.

Response: Returns company object with name, description, website, employee_count, and jobs_count.

Pagination

API responses containing collections are paginated. Use the page and limit query parameters to navigate results.

Meta information about pagination is always included in the pagination object of the response. The has_more boolean indicates if additional pages exist.

Rate Limits

API requests are limited to 100 requests per minute per API key. When you exceed the limit, you will receive a 429 Too Many Requests response.

Rate limit headers are included in every response to help you track usage:

X-RateLimit-Limit: Maximum requests per window
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when the limit resets

Error Codes

JobSphere uses standard HTTP status codes to indicate success or failure of API requests. Errors are returned in a consistent JSON format.

Code	Meaning	Description
400	Bad Request	Malformed request body or missing required parameters
401	Unauthorized	Missing or invalid API key / authentication token
403	Forbidden	Insufficient permissions for the requested action
404	Not Found	Resource does not exist or has been deleted
429	Too Many Requests	Rate limit exceeded. Retry after the reset time.
500	Server Error	Internal server error. Contact support if persistent.