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 1.0
1
© NHS Jobs 2013
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
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.
Version 1.0
2
© NHS Jobs 2013
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)>
<!ELEMENT job_staff_group
<!ELEMENT job_url
Version 1.0
(#PCDATA)>
(#PCDATA)>
3
© NHS Jobs 2013
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 1.0
4
© NHS Jobs 2013
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.
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 1.0
5
© NHS Jobs 2013
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 1.0
6
Defaults to
searching in all
three areas if not
specified.
Defaults to ‘10’ if
© NHS Jobs 2013
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
1
Axy or Axyz
Axy or Axyz
the centre is the approximate centre based on ‘eastings’ and ‘northings’ obtained from the published PAF file.
Version 1.0
7
© NHS Jobs 2013
Attributes
Action
jobtype
Use this field to filter on the type
of job.
Value must be:
‘P’= Permanent
‘F’= Fixed Term
‘B’= Bank
‘H’= Honorary
‘L’= Locum
‘V’= Voluntary
‘TR’= Training
‘S’= Secondment
‘AP’= Apprenticeship
sort_by
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
Value must be:
Defaults to ‘0’ if
simple_view
Version 1.0
Notes
8
Values
‘date’= Most recent first
‘salary’= Highest salary
first
‘Y’= exclude description
Default values
Defaults to most
relevant first, if
not specified.
Defaults to long
descriptions, if not
specified.
© NHS Jobs 2013
Attributes
from_date
Action
Notes
Values
Default values
the search results within your
own web page. This is an
optional attribute used to return
the ‘results only’ without the
header, side and footer
navigation.
‘1’= don’t show
navigation items
not specified.
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
Version 1.0
9
© NHS Jobs 2013
Attributes
Action
pay_band
Use this field to filter on the Pay
Band
Value must be:
‘1’
‘2’
‘3’
‘4’
‘5’
‘6’
‘7’
‘8a’
‘8b’
‘8c’
‘8d’
‘9’
‘CN’=Consultant
‘AS’=Associate
Specialist
‘SG’=Staff Group
‘SR’=Specialty Registrar
staff_group
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
Version 1.0
Notes
10
Values
Default values
© NHS Jobs 2013
Attributes
Action
Notes
Values
Default values
'SG15'= Allied Health
Professionals
'SG30'= Estates &
Ancillary
'SG35'= Healthcare
Scientists
'SG45'= Medical &
Dental
'SG40'= Nursing &
Midwifery Registered
'SG55'= Students
Document Revision
Version
Date
Author
Issue
1.0
6/9/2013
Peter Brown
First published
Version 1.0
11
© NHS Jobs 2013