Getting started

Requesting an API key

Do you want to use the APIs for yourself?

First, you'll need an account on reed.co.uk/recruiter. Then contact us to get your API key.

Do you want to use the APIs on behalf of multiple clients?

To access the APIs on behalf of clients, you'll need your own API key, as well as the Username and Posting key for each client. Please contact us to get your API key.

How do I obtain the Username and Posting key for a client?

The username is simply the email address of the client's reed.co.uk/recruiter account. To get the Posting key, ask the client to:

  • Login to their reed.co.uk/recruiter account
  • Navigate to the "Account settings" section
  • Click on "Get my Posting key"

Security

Please make sure all your API requests will be using SSL. (use the https:// prefix on every URL)

Authenticating API requests

Request elements

When accessing the API, you must provide the following items to authenticate your request:

  • Client ID - every API user is assigned a client ID, along with their API key.
  • Signature - the request signature is calculcated using your API key.
  • Timestamp - the date and time the request was created, represented as a string in UTC.

Authentication steps

Below are the steps for authenticating requests to any of the Recruiter APIs. It is assumed you have your Client ID and API key.

1.) Create a request: construct a request to the API. For more details about specific actions and parameters, please see the API reference.

2.) Create a signature: a string that is signed using your API key. The string must consist of the following concatenated items:

  • HTTP Method used for the request (e.g. GET, POST, PUT)
  • User-agent (e.g. Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0))
  • Full request URL (e.g. https://www.reed.co.uk/recruiter/api/1.0/jobs)
  • Host (always set to www.reed.co.uk)
  • Timestamp (exact same value as the one passed in the X-Timestamp , see below)

Create an HMAC-SHA1 hash of the string using the API key, then Base64 encode the hashed value. See below for some examples showing how to do this in various programming languages.

Note that when creating the SHA1 hash, you can interpret the API key as a string or as a .NET Guid. Both methods are supported.

3.) Send the request: send the request to the API. The timestamp, Client ID and Signature must be provided in the request headers along with some other mandatory headers as follows:

  • ContentType: the content type of the request, e.g. application/x-www-form-urlencoded
  • Method: the HTTP method, e.g. POST, GET or PUT
  • User-Agent: the user agent for your system. This should be the same as the user agent used to calculate your signature
  • X-ApiSignature: signature value
  • X-ApiClientId: Client ID value
  • X-TimeStamp: timestamp value as a UTC string (e.g. 2017-01-01T14:30:23+00:00)

Authentication code examples

If you would like to test your signature, please use our Signature Test page.

Usage limits

The default usage limit for the reed.co.uk Recruiter API is 2,000 requests per hour. This can be customised on a per API user basis, if required. Please contact us for more information.

Jobs API
If you need to reference our legacy 'HTTP posting' service documentation, please click here.

Post job

Adds a new job to the recruiter's account. Requires authentication. Content to be passed in the Request Body.

REQUEST
POST https://www.reed.co.uk/recruiter/api/1.0/jobs
Parameter Value Description
Required parameters
username string Your reed.co.uk account username.
jobType int The type of the job. Possible values:
  • 1 = Permanent
  • 2 = Contract
  • 4 = Temporary
workingHours int The job working hours. Possible values:
  • 1 = Full time
  • 2 = Part time
  • 3 = Full or Part time
description string The job description must be between 150 and 6,500 characters. It cannot contain email addresses, URLs or phone numbers.
title string The job title must be no more than 255 characters. It cannot contain email addresses, html, URLs or phone numbers.
townName* string The job location (e.g. WC2B 5LX, London, Newcastle upon Tyne, Covent Garden). Must be no more than 255 characters. It cannot contain email addresses, html, URLs or phone numbers.

It is recommended to provide a UK postcode as this allows for more accurate searching.

*The townName parameter can only accept postcode and names of towns within the UK.
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used if posting on behalf of clients (bulk posters).
productId int Credit type to be spent when creating the job. Possible values:
  • 1 = Standard job
  • 2 = Premium job
  • 3 = Featured job
  • 4 = Premium+ job
  • 81 = Marketplace job

If no value is provided, the system will use the recruiter's preferred credit type (if set) or automatically choose the best available credit in the account.
expiryInDays int The number of days the job will appear on reed.co.uk. Max of 42. (Default: 42)
isDemo boolean If true, the job will be posted as a draft. Used to test the api works as expected. (Default: false). Only used in Post job (not Edit).
isPublic boolean If true, the job will appear in reed.co.uk's public sector and display in relevant searches. (Default: false)
isGraduate boolean If true, the job will appear in reed.co.uk's graduates sector. This option is used to indicate that the job is a graduate trainee role and is usually aimed to candidates who have graduated within the last three years. (Default: false)
sendApplicationDigest boolean If true, job application emails will be sent to the recruiter in a digest format, once a day. If false, job application emails will be sent instantly. (Default: false)
ownerRef string Optional reference (e.g. recruiter's own job reference). Must be no more than 64 characters. It cannot contain email addresses, html or URLs.
profileId int Optional (for recruiters with extended profile permissions). This references the recruiter's profile ID (which the recruiter has permissions to use) that will be associated with the posted job.

If not provided: The profile associated with the recruiter, if they have one, will automatically be assigned with the job.
If provided: The specified profile will be associated with the job.

Only a recruiter's profile ID, or any the recruiter has permissions to, can be specified against the job.
countyName string Can be used in conjunction with townName to specify a county. (e.g. Essex)
countryName string Can be used in conjunction with townName and/or countyName to specify a country. (e.g. United Kingdom)
parentSectorId
View all
int Can be used to specify the parent sector the job should be posted in. If not provided, the system will set the most appropriate sector automatically, based on the job details.
jobSectorId
View all
int Can be used, together with parentSectorId, to specify the sub-sector the job should be posted in. If not provided, the system will set the most appropriate sector automatically, based on the job details.
minSalary decimal Specifies the minimum salary for the job. If not provided the salary will be shown as "Not specified".
maxSalary decimal Specifies the maximum salary for the job. If not provided the salary will be shown as "Not specified".
currency int Used to specify the salary currency (Default: GBP). Possible values:
  • 1 = GBP (Great Britain Pounds)
  • 2 = EUR (Euro)
  • 3 = AUD (Australian Dollars)
  • 8 = USD (United States Dollars)
  • 21 = CAD (Canadian Dollars
salaryType int Used to specify the salary type. Possible values:
  • 1 = Per hour
  • 2 = Per day
  • 5 = Per annum (Default)
ote boolean

On target earnings. If true, will add "On target earnings" to the salary description.

Default: false.

benefits boolean

If true, will add "plus Benefits" to the salary description.

Default: false.

proRata boolean

If true, will add "pro rata" to the salary description.

Default: false.

negotiable boolean

If true, will add "negotiable" to the salary description.

Default: false.

showSalary boolean

If false, the salary will be hidden on the job details. The specified salary will still be used for searching purposes.

Default: false.

hiddenSalaryDescription int Only used if showSalary is false .

If provided, one of the following description will be shown instead of the salary. Possible values:

  • 0 = Negotiable (Default)
  • 1 = Commision only
  • 2 = Competitive
emailForApplications string

Alternative email address, which can be provided if the user wants to receive job application emails to an email that is different from the Recruiter account email address.

Only valid email addresses will be accepted, for more details on our email validation rules please click here.

eligibleUkOnly boolean

If true, applications made by candidates not eligible to work in the UK will be automatically rejected.

If false, can specify visa sponsorship availability.

Default: true.

isVisaSponsorship boolean Only used if eligibleUkOnly is false (defaults to true).

If true, looking for both UK/non-UK eligible candidates and are open to sponsoring a visa.

If false, looking for both UK/non-UK eligible candidates, but are not open to sponsoring a visa.

Default: not set

externalUrl string

If provided, applicants will be redirected to the specified external application URL. Must be a valid URL and be no more than 500 characters. The user must have a valid subscription to use this feature.

coverLetterPreference int

Used to specify the cover letter preference. Possible values:

  • 1 = Optional
  • 2 = Required
  • 3 = Not Required (Default)
skills[i] string

Can be used to provide a list of skills to associate with the job. (e.g. skills[0]='ASP', skills[1]='JAVA' etc..)

questions.Question[i]

questions.ExpectedAnswer[i]

questions.IsKiller[i]

string

boolean

boolean

Can be used to provide a list of screening questions for the job. The question must consist of a question, an expected answer and wether or not is auto reject.

Example

  • questions[0].Question = 'Do you have experience ?'
  • questions[0].ExpectedAnswer = true
  • questions[0].IsKiller = true
  • questions[1].Question = 'You like your job ?'
  • questions[1].ExpectedAnswer = true
  • questions[1].IsKiller = false

Maximum 5 screening questions can be provided.

locationBaseType

int

Used to indicate job is remote working:

  • 0 = Not Specified (default)
  • 1 = Remote

RESPONSE
  • Returns a status code of 201 (Created) if the job is successfully posted, together with the following data:
    • JobId: the ID of the updated job.
    • ResponseMessage (e.g. Job successfully updated)
  • Returns a status code of 400 (Bad Request) if the request is not well-formed.
  • Returns a status code of 409 (Conflict) if the job is a duplicate or would be producing a duplicate.

Post job code example

Post job error list

Edit job

Edits an existing live job. Requires authentication. Content to be passed in the Request Body.

Notes: it is not possible to edit a draft job (see Post job , isDemo parameter)

REQUEST
PUT https://www.reed.co.uk/recruiter/api/1.0/jobs/update/{jobId}
Parameter Value Description
Required parameters
username string Your reed.co.uk account username.
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used if posting on behalf of clients (bulk posters).
doNotExtend boolean If true, the updated job will retain the expiry date of the existing job.
If false, the job's expiry date will be calculated from the expiryInDays parameter.
(Default: false)
- - All other parameters are the same as those for Post job. All are optional, based on the fields you want to update.
RESPONSE
  • Returns a status code of 200 (OK) if the job is successfully updated, together with the following data:
    • JobId: the ID of the updated job.
    • ResponseMessage (e.g. Job successfully updated)
  • Returns a status code of 400 (Bad Request) if the request is not well-formed.
  • Returns a status code of 409 (Conflict) if the job is a duplicate or would be producing a duplicate.

Edit job code example

Edit job error list

End job

Ends an existing live job. Requires authentication. Content to be passed in the Request Body.

REQUEST
PUT https://www.reed.co.uk/recruiter/api/1.0/jobs/end/{jobId}
Parameter Value Description
Required parameters
username string Your reed.co.uk account username.
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used if posting on behalf of clients (bulk posters).
RESPONSE
  • Returns a status code of 200 (OK) if the job is successfully ended, together with the following data:
    • JobId: the ID of the ended job
    • ResponseMessage (e.g. Job successfully ended)
  • Returns a status code of 400 (Bad Request) if the request is not well-formed.

End job code example

End job error list

Relist job

Relists an existing expired job. Requires authentication. Content to be passed in the Request Body.

REQUEST
PUT https://www.reed.co.uk/recruiter/api/1.0/jobs/relist/{jobId}
Parameter Value Description
Required parameters
username string Your reed.co.uk account username.
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used by bulk posters.
RESPONSE
  • Returns a status code of 200 (OK) if the job is successfully relisted, together with the following data:
    • JobId: the ID of the relisted job.
    • ResponseMessage (e.g. Job successfully relisted)
  • Returns a status code of 400 (Bad Request) if the request is not well-formed.

Relist job code example

Relist job error list

Extend job

Extends an existing live job. Requires authentication. Content to be passed in the Request Body.

REQUEST
PUT https://www.reed.co.uk/recruiter/api/1.0/jobs/extend/{jobId}
Parameter Value Description
Required parameters
username string Your reed.co.uk account username.
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used by bulk posters.
RESPONSE
  • Returns a status code of 200 (OK) if the job is successfully extended, together with the following data:
    • JobId: the ID of the extended job.
    • ResponseMessage (e.g. Job successfully extended)
  • Returns a status code of 400 (Bad Request) if the request is not well-formed.

Extend job code example

Extend job error list

CV Search API

Candidate preview

Retrieves a candidate preview. Requires authentication. Content to be passed in the query string. Won't spend a download credit.

REQUEST
GET URI: https://www.reed.co.uk/recruiter/api/1.0/cvsearch/candidate/{candidateId}/preview
Parameter Value Description
Required parameters
candidateId int Id of the candidate. (as part of the url as shown above)
username string Your reed.co.uk account username (or the reed.co.uk account username of the user you're retrieving the profile on behalf of).
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used by bulk posters when retrieving the profile on behalf of a reed.co.uk recruiter account.
keywords string Search keywords. If passed, CV matches will be generated in the response.
RESPONSE
  • Returns a status code of 200 (OK) if the call is successful, together with the result set:
    • cvSnippets: array of strings containing the CV matches. Only returned if a keyword is provided.
    • eligibility: JSON object containing the following details
      • hasDrivingLicence: true if the candidate has a valid driving licence, false otherwise.
      • hasCar: true if the candidate owns a car, false otherwise.
      • isEligible: true if the candidate is eligible to work in the UK, false otherwise.
      • noticePeriod: string. candidate's notice period.
    • locations: array of objects containing the candidate's preferred work locations.
    • qualifications: array of objects representing the candidate's education. Each object contains: institutionName (string), startedOn (date), finishedOn (date), educationSubjectName (string), qualificationTypeName (string), gradeName (string).
    • skills: array of strings containing the candidate's skills.
    • sectorsAppliedFor: array of objects containing the recently applied for job sectors. (last 3 months)
  • Returns a status code of 400 (Bad Request) if the request is not well-formed.

Candidate preview error list

Download CV

Downloads a candidate CV. Requires authentication. Content to be passed in the query string. Will spend a download credit.

REQUEST
GET URI: https://www.reed.co.uk/recruiter/api/1.0/cvsearch/cv/{candidateId}
Parameter Value Description
Required parameters
candidateId int Id of the candidate. (as part of the url as shown above)
username string Your reed.co.uk account username (or the reed.co.uk account username of the user you're downloading the cv on behalf of).
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used by bulk posters when downloading a cv on behalf of a reed.co.uk recruiter account.
RESPONSE
  • Returns a status code of 200 (OK) if the search is successfully run, together with the result set:
    • A stream of bytes containing the candidate CV.
  • Returns a status code of 400 (Bad Request) if the request is not well-formed

Download CV error list

Candidate profile

Retrieves a candidate profile. Requires authentication. Content to be passed in the query string. Will spend a download credit.

REQUEST
GET URI: https://www.reed.co.uk/recruiter/api/1.0/cvsearch/candidate/{candidateId}
Parameter Value Description
Required parameters
candidateId int Id of the candidate. (as part of the url as shown above)
username string Your reed.co.uk account username (or the reed.co.uk account username of the user you're retrieving the profile on behalf of).
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used by bulk posters when retrieving the profile on behalf of a reed.co.uk recruiter account.
RESPONSE
  • Returns a status code of 200 (OK) if the search is successfully run, together with the result set:
    • candidateId: id of the candidate.
    • forename: candidate's forename.
    • surname: candidate's surname.
    • email: candidate's email.
    • phone: candidate's phone number.
    • lastLogin: candidate's last login date on reed.co.uk.
    • minimumSalary: candidate's yearly minimum salary.
    • minimumTempRate: candidate's hourly minimum salary.
    • isUKEligible: true if the candidate is eligible to work in the UK, false otherwise.
    • jobTitle: candidate's job title.
    • previousEmployer: candidate's previous employer.
    • address: candidate's address.
    • town: candidate's town.
    • postcode: candidate's post code.
    • country: candidate's country.
    • permanentWork: true if the candidate is interested in permanent work, false otherwise.
    • tempWork: true if the candidate is interested in temporary work, false otherwise.
    • contractWork: true if the candidate is interested in contract work, false otherwise.
    • fullTimeWork: true if the candidate is interested in full time work, false otherwise.
    • partTimeWork: true if the candidate is interested in part time work, false otherwise.
    • drivingLicence: true if the candidate has a valid driving licence, false otherwise.
    • carOwner: true if the candidate owns a car, false otherwise.
    • createdOn: candidate's registration date on reed.co.uk.
    • noticePeriod: candidate's notice period.
    • highestQualification: candidate's highest qualification.
    • personalStatement: candidate's personal statement.
    • education: array of objects representing the candidate's education. Each object contains: institutionName (string), startedOn (date), finishedOn (date), subject (string), qualificationType (string), degreeGrade (string), gradeDescription (string).
    • jobSectors: array of objects representing the candidate's preferred sectors. Each object contains: parentSector (string), subSectors (array of string).
    • languages: array of objects representing the languages spoken by the candidate. Each object contains: langauge (string), fluency (string).
    • preferredLocations: array of strings containing the candidate preferred locations.
    • workHistory: array of objects representing the candidate's work history. Each object contains: jobTitle (string), companyName (string), jobDescription (string), dateFrom (date), dateTo (date)
    • skills: array of strings containing the candidate's skills.
  • Returns a status code of 400 (Bad Request) if the request is not well-formed.

Candidate profile error list

Download limits

Retrieves your CV subscription download limits. Requires authentication. Content to be passed in the query string.

isD
REQUEST
GET URI: https://www.reed.co.uk/recruiter/api/1.0/cvsearch/downloadlimits
Parameter Value Description
Required parameters
username string Your reed.co.uk account username (or the reed.co.uk account username of the user you're retrieving the information on behalf of).
Optional parameters
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used by bulk posters when retrieving the information on behalf of a reed.co.uk recruiter account.
RESPONSE
  • Returns a status code of 200 (OK) if the search is successfully run, together with the result set:
    • downloadLimit: the daily download limit of your cv access subscription.
    • usageCount: number of used downloads (for the current day).
    • resetTime: next reset time for the daily downloads allowance.
  • Returns a status code of 400 (Bad Request) if the request is not well-formed.

Download limits error list

CV Search Availability

Runs a CV search with filters validating if the user has credits to search CV's with availability. Requires authentication. Content to be passed in the query string.

REQUEST
GET https://www.reed.co.uk/recruiter/api/1.0/cvsearch/searchavailability
Parameter Value Description
Required parameters
username string Your reed.co.uk account username (or the reed.co.uk account username of the user you're running the search on behalf of).
Optional parameters
keywords string Job title or skill to search for. Boolean expression can be used (e.g. (developer OR programmer) AND java).
location string Candidates location to search on (town or postcode).
postingKey Guid Unique posting key associated with a reed.co.uk recruiter account. Only used by bulk posters when running a search on behalf of a reed.co.uk recruiter account.
titleOnly boolean If true, the keywords are only searched on candidates job titles. If false, the search extends through the whole candidate's CV. (Default: false)
radius int Search location radius. Default to 20 miles. Possible values:
  • 3 = 3 miles
  • 5 = 5 miles
  • 10 = 10 miles
  • 15 = 15 miles
  • 20 = 20 miles
  • 30 = 30 miles
  • 50 = 50 miles
salaryFrom decimal Minimum candidate salary (in GBP)
salaryTo decimal Maximum candidate salary (in GBP)
salaryType int Salary type. Default per annum. Possible values:
  • 1 = per hour
  • 5 = per annum
parentSectors
View all
int array Parent sectors to constrain the search on. (e.g.: parentSectors=2&parentSectors=42)
sectors
sectors
int array Sub sectors to constrain the search on. (e.g. sectors=174§ors=1921)
permanent boolean If true, returns candidates available for permanent work.
temporary boolean If true, returns candidates available for temporary work.
contract boolean If true, returns candidates available for contract work.
fullTime boolean If true, returns candidates available for full time work.
partTime boolean If true, returns candidates available for part time work.
activityType int reed.co.uk website activity type. Defaults to "signed in". Possible values:
  • 1 = signed in
  • 2 = registed
activityTimeFrame int reed.co.uk website activity type time frame. Defaults to "1 month". Possible values:
  • 1 = 1 day
  • 2 = 2 days
  • 7 = 1 week
  • 14 = 2 weeks
  • 30 = 1 month
  • 90 = 3 months
  • 180 = 6 months
  • 365 = 1 year
includeIneligible boolean If true, also returns candidates not eligible to work in the UK.
hasDrivingLicence boolean If true, returns candidates with a driving licence.
isCarOwner boolean If true, returns candidates who own a car.
languages
View all
int array Candidates languages to constrain the search on (e.g languagues=17&languages=18)
languageFluency int Language fluency. Possible values:
  • 1 = Fluent
  • 2 = Intermediate
minimumQualification int Candidates minimum qualification. Possible values:
  • 1 = University degree
  • 2 = Masters degree
  • 4 = PhD
  • 8 = A Level
  • 16 = GCSE
  • 32 = Other
degreeSubjectKeywords string Degree subject.
institutions string array Degree institutions. (e.g. institutions=university of london&institutions=imperial college)
finishedOnStart int Minimum graduating year.
finishedOnEnd int Maximum graduating year.
degreeGrade int Degree grade. Possible values:
  • 1 = First class (valid with University degree)
  • 2 = 2:1 (valid with University degree)
  • 3 = 2:2 (valid with University degree)
  • 4 = Third class (valid with University degree)
  • 5 = Pass (valid with University degree, Masters degree and PhD)
  • 6 = Distinction (valid with Masters degree and PhD)
  • 7 = Merit (valid with Masters degree and PhD)
  • 9 = A* (valid with ALevel and GCSE)
  • 10 = A (valid with ALevel and GCSE)
  • 11 = B (valid with ALevel and GCSE)
  • 12 = C (valid with ALevel and GCSE)
  • 13 = D (valid with ALevel and GCSE)
  • 14 = E (valid with ALevel and GCSE)
  • 16 = F (valid with GCSE)
  • 17 = G (valid with GCSE)
  • 18 = Other (valid with Other)
hasAvailabilityConfirmed boolean Returns candidates who have availability confirmed (default false)
sortBy string CV search results sort order. Possible values:
  • relevancyDesc - relevancy algorithm sorting (default if keywords supplied)
  • registrationDesc - registration date descending
  • activityDesc -last login date descending (default if no keywords supplied)
  • salaryDesc - salary high to low
  • salaryAsc - salary low to high
page int CV search results page number.
pageSize int CV search results page size. Possible values: 5, 10, 25 (default), 50, 100.
RESPONSE
  • Returns a status code of 200 (OK) if the search is successfully run, together with the following json:
    • candidates: json array of matching candidates.
      • candidateId: the ID of the candidate.
      • forename: candidate's forename.
      • surname: candidate's surname.
      • mostRecentEmployer: candidate's most recent employer.
      • preferredWorkLocations: candidate's preferred work locations.
      • permanentWork: true if the candidate is interested in permament work, false otherwise.
      • tempWork : true if the candidate is interested in temporary work, false otherwise.
      • contractWork: true if the candidate is interested in contract work, false otherwise.
      • minimumSalary: candidate's minimum annual salary (in GBP).
      • minimumTempRate: candidate's minimum temp rate (in GBP).
      • mostRecentJobTitle: candidate's most recent job title.
      • createdOn: candidate's registration date.
      • lastCandidateLogin: candidate's last login date.
      • isHidden: true if the candidate has been hidden on cv search on the website, false otherwise.
      • isStarred: true if the candidate has been saved on cv search on the website, false otherwise.
      • workHistory: array of objects containing the candidate's most recent work experience (up to three).
      • isRecentlyViewed: true if the candidate has been recently (last 30 days) viewed on reed.co.uk/recruiter.
    • totalResults: total number of matching candidates.
    • page: current page number.
    • pageSize: current page size.
  • Returns the message "You don't have access to CV Search. You need a valid subscription or CV Search credits.", if the user has no access to execute the search.

RUNNING ANONYMOUS SEARCHES
  • If running a search without an active CV access subscription, the following fields in the response will be null:
    • forename
    • surname
    • mostRecentEmployer
    • workHistory - everything apart from jobTitle

Search CVs error list

close x