Developer Resources

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

Developer Resources

Integration Guides

Learn how to integrate your applications with the NHSJob platform using our comprehensive guides and code examples.

Quick Navigation

Getting Started
Authentication Guide
Job Listings Integration
Application Submission
Webhooks Integration

Getting Started

Welcome to the NHSJob integration guides. This documentation will help you integrate your applications with the NHSJob platform to access healthcare job listings, manage applications, and more.

Before you begin, make sure you have:

Registered for a developer account on the NHSJob Developer Portal
Created an application and obtained your API credentials
Familiarized yourself with our API documentation

Authentication Guide

NHSJob offers two authentication methods for API access:

API Key Authentication

API key authentication is suitable for server-to-server integrations and read-only operations. To use API key authentication:

Log in to the Developer Dashboard
Navigate to the "Applications" section
Select your application and generate an API key
Include the API key in the X-API-Key header with all your requests

Example API Key Request:

curl -X GET "https://api.nhsjob.net/v1/jobs?specialty=nursing" -H "X-API-Key: your_api_key_here"

OAuth 2.0 Authentication

OAuth 2.0 authentication is recommended for applications that need to perform actions on behalf of users. To implement OAuth 2.0:

Configure the OAuth settings in your Developer Dashboard
Implement the authorization code flow in your application
Exchange the authorization code for an access token
Include the access token in the Authorization header with all your requests

Example OAuth Request:

curl -X POST "https://api.nhsjob.net/v1/applications" -H "Authorization: Bearer your_oauth_token_here" -H "Content-Type: application/json" -d '{"job_id":"job_12345","candidate_id":"cand_54321","resume_url":"https://example.com/resume.pdf"}'

Job Listings Integration

This guide explains how to integrate NHSJob job listings into your application or website.

Fetching Job Listings

To retrieve job listings, use the /api/v1/jobs endpoint with appropriate filters:

Example JavaScript Implementation:

// Fetch jobs with filters
async function fetchJobs(filters) {
  const queryParams = new URLSearchParams(filters).toString();
  const response = await fetch(
    `https://api.nhsjob.net/v1/jobs?${queryParams}`,
    {
      headers: {
        'X-API-Key': 'your_api_key_here'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error('Failed to fetch jobs');
  }
  
  return await response.json();
}

Implementing Job Search

To implement a job search feature, create a form that collects user search parameters and passes them to the API.

Example React Implementation:

import React, { useState } from 'react';

function JobSearch() {
  const [jobs, setJobs] = useState([]);
  const [filters, setFilters] = useState({
    specialty: '',
    location: '',
    contract_type: ''
  });
  
  const handleInputChange = (e) => {
    setFilters({
      ...filters,
      [e.target.name]: e.target.value
    });
  };
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    try {
      // Call the fetchJobs function from above
      const data = await fetchJobs(filters);
      setJobs(data.data);
    } catch (error) {
      console.error(error);
    }
  };
  
  return (
    <div>
      {/* Search form implementation */}
      <form onSubmit={handleSubmit}>
        {/* Form fields */}
      </form>
      
      {/* Results display */}
      <div className="jobs-list">
        {jobs.map(job => (
          <div key={job.id} className="job-card">
            {/* Job card content */}
          </div>
        ))}
      </div>
    </div>
  );
}

Application Submission

This guide explains how to implement job application submission through the NHSJob API.

Submitting an Application

To submit a job application, use the /api/v1/applications endpoint with OAuth 2.0 authentication:

Example Application Submission:

// Submit an application
async function submitApplication(applicationData, token) {
  try {
    const response = await fetch('https://api.nhsjob.net/v1/applications', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(applicationData)
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(errorData.message || 'Failed to submit application');
    }
    
    return await response.json();
  } catch (error) {
    console.error('Application submission error:', error);
    throw error;
  }
}

Webhooks Integration

Webhooks allow your application to receive real-time notifications about events in the NHSJob platform.

Available Webhook Events

job.created - Triggered when a new job is posted
job.updated - Triggered when a job listing is updated
job.closed - Triggered when a job listing is closed
application.submitted - Triggered when a new application is submitted
application.status_changed - Triggered when an application status changes

Setting Up Webhooks

Log in to the Developer Dashboard
Navigate to the "Webhooks" section
Click "Add Webhook"
Enter your endpoint URL and select the events you want to subscribe to
Generate a webhook secret for signature verification

Handling Webhook Events

When an event occurs, NHSJob will send an HTTP POST request to your endpoint with a JSON payload containing event details.

Example Webhook Handler (Node.js/Express):

// Express route handler for webhooks
app.post('/webhook/nhsjob', (req, res) => {
  // Verify the webhook signature (implementation not shown)
  // if (!verifySignature(req)) {
  //   return res.status(401).send('Invalid signature');
  // }
  
  const event = req.body;
  
  // Handle different event types
  switch (event.type) {
    case 'job.created':
      console.log('New job created:', event.data.id);
      // Update your local job database
      break;
      
    case 'application.submitted':
      console.log('New application received:', event.data.application_id);
      // Notify relevant users
      break;
      
    case 'application.status_changed':
      console.log(
        'Application ' + event.data.application_id + 
        ' status changed to ' + event.data.status
      );
      // Update application status in your system
      break;
      
    default:
      console.log('Unhandled event type:', event.type);
  }
  
  // Acknowledge receipt of the webhook
  res.status(200).send('Webhook received');
});

Developer Resources