Developer Resources

Build innovative healthcare recruitment solutions with NHSJob's developer tools and APIs.

Developer Resources

API Documentation

The NHSJob API provides programmatic access to job listings, applications, and candidate data. Use our RESTful API to integrate NHSJob functionality into your healthcare recruitment applications.

Authentication

All API requests require authentication. We support two authentication methods:

API Key: For server-to-server integrations and read-only operations
OAuth 2.0: For applications acting on behalf of users

API Key Authentication

Include your API key in the request header:

X-API-Key: your_api_key_here

OAuth 2.0 Authentication

Include the bearer token in the Authorization header:

Authorization: Bearer your_oauth_token_here

Endpoints

GET/api/v1/jobs

Description

Retrieve a list of available jobs with filtering options

Authentication

API Key

Parameters

Name	Type	Required	Description
page	integer	No	Page number for pagination
limit	integer	No	Number of results per page
specialty	string	No	Filter by medical specialty
location	string	No	Filter by location
contract_type	string	No	Filter by contract type (permanent, temporary, etc.)

Response Example

{
  "data": [
    {
      "id": "job_12345",
      "title": "Senior Nurse - Cardiology",
      "description": "We are seeking an experienced Senior Nurse to join our Cardiology department...",
      "location": "London",
      "specialty": "Cardiology",
      "salary_range": "£45,000 - £55,000",
      "contract_type": "Permanent",
      "posted_at": "2025-04-15T10:30:00Z"
    },
    {
      "id": "job_12346",
      "title": "Junior Doctor - Emergency Medicine",
      "description": "An exciting opportunity for a Junior Doctor to join our Emergency Department...",
      "location": "Manchester",
      "specialty": "Emergency Medicine",
      "salary_range": "£38,000 - £45,000",
      "contract_type": "Temporary",
      "posted_at": "2025-04-14T09:15:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 15,
    "total_count": 143
  }
}

GET/api/v1/jobs/:id

Description

Retrieve detailed information about a specific job

Authentication

API Key

Parameters

Name	Type	Required	Description
id	string	Yes	Unique identifier for the job

Response Example

{
  "id": "job_12345",
  "title": "Senior Nurse - Cardiology",
  "description": "We are seeking an experienced Senior Nurse to join our Cardiology department...",
  "requirements": "Minimum 5 years experience in Cardiology nursing. BSc in Nursing required.",
  "responsibilities": "Lead a team of nurses, coordinate patient care, maintain medical records...",
  "location": "London",
  "hospital": "Royal London Hospital",
  "specialty": "Cardiology",
  "salary_range": "£45,000 - £55,000",
  "contract_type": "Permanent",
  "hours": "Full-time",
  "benefits": ["NHS Pension", "28 days annual leave", "Professional development opportunities"],
  "contact_email": "recruitment@royallondon.nhs.uk",
  "posted_at": "2025-04-15T10:30:00Z",
  "application_deadline": "2025-05-15T23:59:59Z"
}

POST/api/v1/applications

Description

Submit a job application

Authentication

OAuth 2.0

Parameters

Name	Type	Required	Description
job_id	string	Yes	ID of the job being applied for
candidate_id	string	Yes	ID of the candidate applying
cover_letter	string	No	Cover letter text
resume_url	string	Yes	URL to the candidate's resume

Response Example

{
  "application_id": "app_67890",
  "status": "submitted",
  "submitted_at": "2025-05-01T14:22:33Z",
  "job_id": "job_12345",
  "candidate_id": "cand_54321"
}

Rate Limits

To ensure fair usage and system stability, the NHSJob API implements rate limiting:

Free tier: 100 requests per hour
Standard tier: 1,000 requests per hour
Enterprise tier: 10,000 requests per hour

Rate limit information is included in the response headers:

X-RateLimit-Limit: 1000\nX-RateLimit-Remaining: 950\nX-RateLimit-Reset: 1620000000

Support

If you have any questions or need assistance with the NHSJob API, please contact our developer support team at api-support@nhsjob.net.