Developer Resources

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

Developer Resources

API Documentation

Explore our comprehensive API documentation to integrate with the NHSJob platform. Our RESTful API provides access to job listings, applications, and candidate data with robust authentication.

Getting Started

Introduction

Welcome to the NHSJob API documentation. This comprehensive guide will help you understand how to integrate with our platform to access healthcare job listings, manage applications, and connect with healthcare professionals across the UK.

Our documentation is organized into sections covering authentication, endpoints, data models, and common use cases to help you build successful integrations.

Authentication

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

API Key Authentication: Simple authentication using an API key in the request header.
OAuth 2.0: More secure authentication for applications acting on behalf of users.

You can obtain your API keys from the Developer Dashboard after registering for a developer account.

Core Concepts

Data Models

Understanding the core data models is essential for working with the NHSJob API. Here are the primary resources you'll interact with:

Jobs: Healthcare positions available on the platform.
Employers: NHS trusts, hospitals, and other healthcare organizations.
Candidates: Healthcare professionals seeking employment.
Applications: Job applications submitted by candidates.

Rate Limits

To ensure fair usage and system stability, the NHSJob API implements rate limiting. The limits vary based on your subscription tier:

Plan	Requests/Minute	Daily Limit
Free	60	10,000
Professional	300	50,000
Enterprise	1,000	Unlimited

Rate limit headers are included in all API responses to help you track your usage.

API Reference

Jobs API

The Jobs API allows you to search, retrieve, and manage job listings on the NHSJob platform.

GET /api/v1/jobs

Retrieves a list of available jobs with filtering options.

Query Parameters:

keywords - Search terms (e.g., "nurse", "doctor")
location - City or region (e.g., "London")
radius - Search radius in miles (default: 10)
specialty - Medical specialty (e.g., "cardiology")
employment_type - Job type (e.g., "full-time", "part-time")
page - Page number for pagination (default: 1)
limit - Results per page (default: 20, max: 100)

GET /api/v1/jobs/{job_id}

Retrieves detailed information about a specific job.

Applications API

The Applications API allows candidates to apply for jobs and employers to manage applications.

POST /api/v1/applications

Submit a new job application.

Request Body:

{
  "job_id": "job_12345",
  "candidate_id": "cand_67890",
  "cover_letter": "I am writing to express my interest...",
  "resume_url": "https://storage.nhsjob.net/resumes/resume_12345.pdf",
  "answers": [
    {
      "question_id": "q_1",
      "answer": "Yes, I have 5 years of experience..."
    }
  ]
}

GET /api/v1/applications

Retrieve applications with filtering options.

Developer Resources