NHS Jobs List Employer Adverts
Purpose
The purpose of this document is to describe the process and identify the different options that you
have when listing your organisation’s job adverts from NHS Jobs on your website or intranet, using
the NHS Jobs List Employer Adverts interface. This document and the interface service is only for the
use of NHS organisations enabled and authorised to use NHS Jobs.
Listing adverts
Once you have posted your job adverts on the NHS Jobs website they will be accessible through the
NHS Jobs online search features and Jobs by Email to job hunters on the internet.
Those identified as for ‘All NHS Jobs Visitors’ will be available to any job seekers with public internet
access to the Wold wide Web. Those identified as for ‘Internal Only’ can be available to an
organisation’s own employees and will not be available to job seekers visiting the NHS Jobs website
or receiving Jobs by Email from NHS Jobs.
You can list your job adverts, both ‘All NHS Jobs Visitors’ and ‘Internal Only’, from or within your own
website or intranet (‘Internal Only’ adverts should only be available through your own intranet, to
avoid receiving applications from job seekers outside of your organisation.)
You can do this in one of the following ways:
1.
you can put a button, banner
or link on your website or intranet which, when selected, will display a page from the NHS
Jobs site listing your vacancies only.
2.
you can put a button, banner
or link on your website or intranet which, when selected, will return a list of your vacancies
in xml format which can then be formatted on your website or intranet to be displayed as
part of it.
These options are explained further in the following pages.
Version 0.3
DRAFT – for information
1
Option 1
The first option will result in an NHS Jobs service page listing your vacancies being displayed with all
navigable options available to the jobseeker as shown in Figure 1.
Figure 1 - Option 1 search results page
Using option 1 means that the visitor will be viewing the list directly on NHS Jobs website, not your
website, and will have all NHS Jobs search and refine features available to them. You could display
this information in a new browser window/tab so that your website remains open in their browser.
For this option, use the following url with the button, banner or link (where the number 123456 is
replaced by your client_id1 ):
www.jobs.nhs.uk/extsearch?client_id=123456
Version 0.3
DRAFT – for information
2
Your client_id is the unique identifier used to identify an organisation within the NHS Jobs system. This is not your vpd_code. You can
see your client_id by looking at your “Employer details” page on the NHS Jobs site.
Option 2
The second option allows the results to be embedded within your website or intranet under your
control. In this case NHS Jobs will return the raw data in an RSS feed xml structure. You will need to
produce the necessary software to format the data, with styles and images held locally, as required
upon the page on your website or intranet.
To do this simply use ‘search_rss’ instead of ‘extsearch’ in the url.
www.jobs.nhs.uk/search_rss?client_id=123456
The xml structure returned is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT nhs_search (status, vacancy_details*) >
<!ELEMENT status (number_of_jobs_found, message*)>
<!ELEMENT number_of_jobs_found (#PCDATA)>
<!ELEMENT message
(#PCDATA)>
<!ELEMENT vacancy_details (id, job_reference, job_title, job_description, job_employer, job_type,
job_specialty?, job_salary, job_location, job_closedate, job_postdate, job_staff_group, job_url)>
<!ELEMENT id
(#PCDATA)>
<!ELEMENT job_reference (#PCDATA)>
<!ELEMENT job_title
(#PCDATA)>
<!ELEMENT job_description (#PCDATA)>
<!ELEMENT job_employer
<!ELEMENT job_type
(#PCDATA)>
(#PCDATA)>
<!ELEMENT job_specialty (#PCDATA)>
<!ELEMENT job_salary
(#PCDATA)>
<!ELEMENT job_location (#PCDATA)>
<!ELEMENT job_closedate (#PCDATA)>
<!ELEMENT job_postdate (#PCDATA)>
Version 0.3
DRAFT – for information
3
<!ELEMENT job_staff_group
<!ELEMENT job_url
(#PCDATA)>
(#PCDATA)>
Element definitions:
nhs_search – root element, this contains all other elements.
status – contains the elements listed below.
number_of_jobs_found - contains the overall number of search results.
message – contains error message generated by the request.
vacancy_details – contains the elements listed below, all of which make up the individual
vacancy.
id – internal reference to the vacancy.
job_reference – contains the reference from the job advert. This is structured as
[vpd_code] & ’-‘ & [original reference] eg. 123-1234
job_title – the Position Title from the job advert.
job_description – some selected text from the main text component of the job advert.
The text will contain html formatting to highlight the terms matched from the original
query.
job_employer – the employer organisation advertising the job.
job_type – the job type of the vacancy.
job_specialty – the Specialty/Function from the job advert.
job_salary – the salary from the job advert.
job_location – the Displayed Location from the job advert. Note that the detail from
the Postcode field is not included.
job_closedate – the current expiry date from the job advert.
job_postdate – the creation date from the job advert.
Job_staff_group – the staff group category for the vacancy.
job_url – the link to the vacancy details on the NHS Jobs website.
Version 0.3
DRAFT – for information
4
Version 0.3
DRAFT – for information
5
Setting up your own search
You can set up your own search links by including any of the attributes below in the search string.
Search links can be used to provide the visitor to your website with a link to quickly perform a predefined search on your jobs advertised on NHS Jobs. Examples of this could include:
For “Internal Only” jobs
www.jobs.nhs.uk/extsearch?client_id=123456&internal_only=Y
www.jobs.nhs.uk/search_rss?client_id=123456&internal_only=Y
For “scientist” jobs
www.jobs.nhs.uk/extsearch?client_id=123456&keywords=scientist&field=title
www.jobs.nhs.uk/search_rss?client_id=123456&keywords=scientist&field=title
For “nursing” jobs
www.jobs.nhs.uk/extsearch?client_id=123456&keywords=nurse nursing&field=title
www.jobs.nhs.uk/search_rss?client_id=123456&keywords=nurse nursing&field=title
For jobs including “Day Care” in advert text
www.jobs.nhs.uk/extsearch?client_id=123456&keywords='day care'&field=description
www.jobs.nhs.uk/search_rss?client_id=123456&keywords='day care'&field=description
For jobs including “Day Care” or “child” in job title
www.jobs.nhs.uk/extsearch?client_id=123456&keywords='day care' child&field=title
www.jobs.nhs.uk/search_rss?client_id=123456&keywords='day care' child&field=title
(where ‘123456’ is your client ID)
A search form, or search box, would be a form on your website where the visitor can enter the
term(s) they are searching for. When the visitor activates the search, the values entered would
produce the necessary search on the NHS Jobs database and list the results on your website. An
example is available upon request.
Version 0.3
DRAFT – for information
6
Some of the additional attributes that you may wish to include in search links or a search form are
listed on the following pages.
Version 0.3
DRAFT – for information
7
Table 1 Search attributes
Attributes
Action
Notes
client_id
Use this to ensure that all jobs
are limited to your employer id
comma separate multiple
employer_ids if necessary
internal_only
Use this to ensure that only jobs
marked as ‘Internal Only’ are
listed.
If this parameter is used then
you must also include a
“client_id” parameter
Use this to filter on the job title,
advert description or job
reference.
If this parameter is used then
you should also include a
“field” parameter
keywords
Values
Default values
Value must be:
Y
If more than one keyword,
separate them with spaces
field
Directs the use of keyword
searching to relevant fields
Only required if “keywords” is
also used.
Value must be:
title
description
ref
location
To filter on the vacancy postcode
use this parameter
If this parameter is used the
you should also include a
“distance=” parameter
Value should be outer
postcode e.g. ‘BN11’ is
the outer postcode of
‘BN11 1EG’
distance
The location search can be
expanded in radial increments.
Only required if “location” is
Value must be:
Version 0.3
DRAFT – for information
Defaults to
searching in all
three areas if not
specified.
Defaults to ‘10’ if
8
Attributes
Action
Notes
Values
Default values
Using E only returns jobs where
there is an exact match with
either the Displayed Location or
the Postcode. Using any of the
number values searches for jobs
in other locations where the
centre1 of the locations are within
the radial distance (eg within 3
miles).
also used.
‘E’ = exact location only
not specified.
‘5’ = within 5 miles
‘10’ = within 10 miles
‘20’ = within 20 miles
‘30’ = within 30 miles
‘50’ = within 50 miles
client_name
To filter on Employer Name use
this parameter.
min_salary
Use this and the following field to
filter the search to jobs between
2 values
Value format of ‘A’ followed
by two or three digits as the
number of thousands of
pounds.
(eg. A23 for £23,000)
Value must be of format:
Use this field with the previous
field to filter the search to jobs
between 2 values
Value format of ‘A’ followed
by two or three digits as the
number of thousands of
pounds.
(eg. A23 for £23,000)
Value must be of format:
max_salary
jobtype
1
Use this field to filter on the type
Axy or Axyz
Axy or Axyz
Value must be:
the centre is the approximate centre based on ‘eastings’ and ‘northings’ obtained from the published PAF file.
Version 0.3
DRAFT – for information
9
Attributes
Action
Notes
Values
Default values
of job.
‘P’= Permanent
‘F’= Fixed Term
‘B’= Bank
‘H’= Honorary
‘L’= Locum
‘V’= Voluntary
‘TR’= Training
‘S’= Secondment
‘AP’= Apprenticeship
Used to control the order in
which the search results are
displayed.
Value must be:
Used to control whether the
shorter form of the job advert is
shown.
Value must be:
daysback
Used to control how recent the
returned jobs should be
Value must be:
‘7’= in the last 7 Days
‘3’= in the last 3 Days
‘2’= in the last 2 Days
‘0’= Today
Defaults to all
jobs if not
specified.
resonly
Use this if you want to embed
the search results within your
Value must be:
Defaults to ‘0’ if
not specified.
sort_by
simple_view
Version 0.3
DRAFT – for information
‘date’= Most recent first
‘salary’= Highest salary
first
‘Y’= exclude description
‘1’= don’t show
Defaults to most
relevant first, if
not specified.
Defaults to long
descriptions, if not
specified.
10
Attributes
from_date
Action
Notes
Values
own web page. This is an
optional attribute used to return
the ‘results only’ without the
header, side and footer
navigation.
navigation items
Use this if you want to filter the
search results by the date they
were published on NHS Jobs
Format must be:
‘0’= show navigation
items
“DD-MMM-YYYY”
department
Use this to filter on text within the
department field
area_of_work
Use this field to filter on the Area
of Work.
Value must be a code
value for the area of
work category. Please
see ‘Area of Work list’
document.
pay_scheme
Use this field to filter on the Pay
Scheme
Value must be:
‘AC’=Agenda for Change
‘MD’=Hospital Medical
and Dental
‘SM’=Very Senior
Manager
‘OT’=Other
pay_band
Use this field to filter on the Pay
Value must be:
Version 0.3
DRAFT – for information
Default values
11
Attributes
staff_group
Version 0.3
Action
Notes
Values
Band
‘1’
‘2’
‘3’
‘4’
‘5’
‘6’
‘7’
‘8a’
‘8b’
‘8c’
‘8d’
‘9’
‘CN’=Consultant
‘AS’=Associate
Specialist
‘SG’=Staff Group
‘SR’=Specialty Registrar
Use this field to filter on the Staff
Group, to separate out different
categories of adverts
Value must be:
'ANY'= any staff group
'SG20'= Additional
Clinical Services
'SG25'= Additional
Professional Scientific &
Technical
'SG10'= Administrative &
Clerical
'SG15'= Allied Health
DRAFT – for information
Default values
12
Attributes
Action
Notes
Values
Default values
Professionals
'SG30'= Estates &
Ancillary
'SG35'= Healthcare
Scientists
'SG45'= Medical &
Dental
'SG40'= Nursing &
Midwifery Registered
'SG55'= Students
Document Revision
Version
Date
Author
Issue
0.1
24/09/2012
Peter Brown
First draft.
0.2
6/10/2012
Peter Brown
First revision after review.
0.3
22/02/2013
Peter Brown
Revised after review
Version 0.3
DRAFT – for information
13