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
Our Legacy Job Posting APIs have been deprecated. You can access the new API documentation here: API V2.
Candidate Search

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