Reed.co.uk for Developers - Recruiter APIs

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

var domain = "www.reed.co.uk";
var userAgent = "ReedAgent";
var apiToken = "your_api_token";
var clientId = "your_client_id";
var url = $"https://{domain}/recruiter/api/1.0/jobs";
var httpMethod = "POST";
var timeStamp = DateTime.Now.ToString("yyyy-MM-ddTHH:mm:sszzz");
var stringToSign = $"{httpMethod}{userAgent}{url}{domain}{timeStamp}";

// Note that the API token can be treated as a .NET GUID or a string.
// The following line could be replaced with 'var hmacsha1 = new HMACSHA1(Encoding.ASCII.GetBytes(apiToken));'
// which generates a different signature but is equally valid.
var hmacsha1 = new HMACSHA1(new Guid(apiToken).ToByteArray());
byte[] byteArray = Encoding.ASCII.GetBytes(stringToSign);
var calculatedSignature = Convert.ToBase64String(hmacsha1.ComputeHash(byteArray));

// Add the required headers:
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("ContentType", "application/x-www-form-urlencoded");
httpClient.DefaultRequestHeaders.Add("Method", "POST");
httpClient.DefaultRequestHeaders.Add("User-Agent", userAgent);
httpClient.DefaultRequestHeaders.Add("X-ApiSignature", calculatedSignature);
httpClient.DefaultRequestHeaders.Add("X-ApiClientId", clientId.ToString());
httpClient.DefaultRequestHeaders.Add("X-TimeStamp", timeStamp);
                                            
var postData = new List<KeyValuePair<string, string>>();
// job data goes here
// e.g. postData.Add(new KeyValuePair<string, string>("title","My job title"));

using (var content = new FormUrlEncodedContent(postData))
{
    var response = await httpClient.PostAsync(url, content);
}

<?php
$user_agent = 'ReedAgent';
$api_token = 'your_api_token';
$client_id = 'your_client_id';
$url = 'https://www.reed.co.uk/recruiter/api/1.0/jobs';
$http_method = 'POST';

$dt = new DateTime('now', new DateTimeZone('UTC'));
$timestamp = $dt->format('Y-m-d\TH:i:s') . '+00:00';

// Calculate signature
$string_to_sign = $http_method . $user_agent . urldecode($url) . parse_url($url, PHP_URL_HOST) . $timestamp;
$hmac_sha1_hash = hash_hmac('sha1', $string_to_sign, $api_token , true);
$api_signature = base64_encode($hmac_sha1_hash);

// Add required headers
$headers = array();
$headers[] = 'ContentType: application/x-www-form-urlencoded';
$headers[] = 'Method: ' . $http_method;
$headers[] = 'User-Agent: ' . $user_agent;
$headers[] = 'X-ApiSignature: ' . $api_signature;
$headers[] = 'X-ApiClientId: ' . $client_id;
$headers[] = 'X-TimeStamp: ' . $timestamp;

// Construct job data
$data = array(
    // Job details go here
    // e.g. 'title' => 'My job title'
);

// Build request using cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_USERAGENT, $user_agent);
curl_setopt($ch, CURLOPT_URL, $url);

if($http_method == 'POST') {
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
}

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 3);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);

// Make API call
$response = curl_exec($ch);
curl_close($ch);
?>

let request = require('request');
let crypto = require('crypto');
let moment = require('moment');

let domain = 'www.reed.co.uk';
let userAgent = 'ReedAgent';
let apiToken = 'your_api_token';
let clientId = 'your_client_id';
let url = 'https://' + domain + '/recruiter/api/1.0/jobs';
let httpMethod = 'POST';
let timeStamp = moment().format('YYYY-MM-DDTHH:mm:ssZ'); // timeStamp should be in '2017-01-01T14:30:23+00:00' format

let stringToSign = httpMethod + userAgent + url + domain + timeStamp;
let signature =
    new Buffer(
        crypto.createHmac('sha1', apiToken)
        .update(stringToSign)
        .digest()
    ).toString('base64');

// Build a request with the required headers
let options = {
    url: url,
    headers: {
        'ContentType': 'application/x-www-form-urlencoded',
        'Method': httpMethod,
        'User-Agent': userAgent,
        'X-ApiSignature': signature,
        'X-ApiClientId': clientId,
        'X-TimeStamp': timeStamp
    },
    form: {
        // values to post
        // e.g. title:'My job title'
    }
};

// Post the request
request.post(options, callback);

# Auth + CV search example
use POSIX qw(strftime);
use Digest::MD5 qw(md5_hex);
use Digest::SHA qw(sha1 sha1_hex sha1_base64 hmac_sha1_base64);
use LWP::Simple;
sub guid_to_dotnet_guid
{
    my @guid = split //,$_[0];
    @guid = map(ord, @guid);
    my @new_guid_order = (6,7,4,5,2,3,0,1,11,12,9,10,16,17,14,15,19,20,21,22,24,25,26,27,28,29,30,31,32,33,34,35);
    my @reordered_guid = @guid[@new_guid_order];
    my $new_guid = join("", map(chr, @reordered_guid));
    @array = ( $new_guid =~ m/../g );
    my @final_array;
    foreach(@array){
        push(@final_array, hex($_));
    };
    $new_guid = join("", map(chr, @final_array));
	
    return $new_guid;
}
my $key = "7e94901a-f6a2-4b97-a1df-0bafdeba3b99"; # API Token -- REPLACE THIS WITH YOUR API TOKEN
my $api_client_id = '1'; # API Client ID -- REPLACE THIS WITH YOUR API CLIENT ID
my $now_string = strftime "%Y-%m-%dT%H:%M:%S", localtime; # Timestamp (to use in the signature string and in the headers)
my $posting_key = "7e94901a-f6a2-4b97-a1df-0bafdeba3b99"; # Posting Key (see api doc) -- REPLACE THIS WITH A VALID POSTING KEY (IF NEEDED)
my $username = "email\@email.com"; # Client username (see api doc) (please note that in perl email addresses must be passed like myname\@mydomain.com (note the escaping of \@). -- REPLACE THIS WITH A VALID EMAIL ADDRESS (IF NEEDED)(see doc)
my $host = "www.reed.co.uk"; 
my $user_agent = 'PerlTest'; # Your user agent
my $search_url = "https://".$host."/recruiter/api/1.0/cvsearch/";
my $search_query_string = "postingKey=".$posting_key."&username=".$username; 
my $signature_string = "GET".$user_agent.$search_url. "?" .$search_query_string.$host.$now_string; # string to sign made of: HttpMethod + UserAgent + SearchUrl + QueryString + Host + TimeStamp
my $browser = LWP::UserAgent->new;
my $dotnet_guid = guid_to_dotnet_guid($key); # this is needed because of the different guid representation in .NET 
my $digest = hmac_sha1_base64($signature_string, $key); # compute the hash of signature_string using dotnet_guid as key
my $full_url = $search_url."?".$search_query_string;
my $response = $browser->get( $full_url,
    'Content_type'   => 'application/json',
    'Method'         => 'GET',
    'X-ApiClientId'  => $api_client_id,
    'X-TimeStamp'    => $now_string,
    'X-ApiSignature' => $digest."=",
    'User-Agent'     => $user_agent
    );

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

var postData = new List<KeyValuePair<string, string>>();
postData.Add(new KeyValuePair<string, string>("Title", "This is my test job"));
postData.Add(new KeyValuePair<string, string>("JobType", "1"));
postData.Add(new KeyValuePair<string, string>("Description", "This is my test job description, please ignore this and do not apply.  Thank you the reed.co.uk team."));


postData.Add(new KeyValuePair<string, string>("TownName", "southgate"));
postData.Add(new KeyValuePair<string, string>("CountyName", "london"));
postData.Add(new KeyValuePair<string, string>("CountryName", "UK"));
postData.Add(new KeyValuePair<string, string>("WorkingHours", "1"));
postData.Add(new KeyValuePair<string, string>("EmailForApplications", clientDetails.Username));


postData.Add(new KeyValuePair<string, string>("MinSalary", "15000"));
postData.Add(new KeyValuePair<string, string>("MaxSalary", "25000"));
postData.Add(new KeyValuePair<string, string>("Currency", "2"));
postData.Add(new KeyValuePair<string, string>("ExpiryInDays", "42"));
postData.Add(new KeyValuePair<string, string>("ProductId", "2"));
postData.Add(new KeyValuePair<string, string>("PostingKey", @Model.ClientDetails.PostingKey));
postData.Add(new KeyValuePair<string, string>("Username", @Model.ClientDetails.Username));
postData.Add(new KeyValuePair<string, string>("IsDemo", "true"));
postData.Add(new KeyValuePair<string, string>("Skills[0]", "skill1"));
postData.Add(new KeyValuePair<string, string>("Skills[1]", "skill2"));
postData.Add(new KeyValuePair<string, string>("CoverLetterPreference", "3"));
HttpContent content = new FormUrlEncodedContent(postData);

try
{
    var resp = httpClient.PostAsync(url, content).Result;


    var stringContent = resp.Content.ReadAsStringAsync().Result;


}
catch (Exception)
{
    // Exception Handling   
}

Post job error list

Response (HTTP)	Error Type	Message
NotFound (404)	Invalid Ecruiter	"Invalid ecruiter"
NotFound (404)	Invalid Username	"Invalid ecruiter username provided."
BadRequest (400)	Invalid Job Id	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "job Id": [ "Job not found, please provide a valid job id."] } }
PreconditionFailed (412)	Model with validation errors	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "JobType": [ "Please provide a valid job type eg. Perm"] } }
Conflict (409)	Job already exists	"Job not added: This job already exists on reed.co.uk, and is not set to expire in the next 7 days."
InternalServerError (500)	Unexpected Error	"Job Api error. An error has occured the technical team have been informed."

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

var postData = new List<KeyValuePair<string, string>>();
postData.Add(new KeyValuePair<string, string>("Title", "This is my test job that has been updated"));
postData.Add(new KeyValuePair<string, string>("JobType", "1"));
postData.Add(new KeyValuePair<string, string>("Description", "This is my test job description, please ignore this and do not apply.  Thank you the reed.co.uk team."));
postData.Add(new KeyValuePair<string, string>("TownName", "southgate"));
postData.Add(new KeyValuePair<string, string>("CountyName", "london"));
postData.Add(new KeyValuePair<string, string>("CountryName", "UK"));
postData.Add(new KeyValuePair<string, string>("WorkingHours", "1"));
postData.Add(new KeyValuePair<string, string>("EmailForApplications", clientDetails.Username));
postData.Add(new KeyValuePair<string, string>("MinSalary", "15000"));
postData.Add(new KeyValuePair<string, string>("MaxSalary", "25000"));
postData.Add(new KeyValuePair<string, string>("Currency", "2"));
postData.Add(new KeyValuePair<string, string>("ExpiryInDays", "42"));
postData.Add(new KeyValuePair<string, string>("ProductId", "2"));
postData.Add(new KeyValuePair<string, string>("PostingKey", @Model.ClientDetails.PostingKey));
postData.Add(new KeyValuePair<string, string>("Username", @Model.ClientDetails.Username));
postData.Add(new KeyValuePair<string, string>("IsDemo", "true"));
postData.Add(new KeyValuePair<string, string>("Skills[0]", "skill1"));
postData.Add(new KeyValuePair<string, string>("Skills[1]", "skill2"));
postData.Add(new KeyValuePair<string, string>("CoverLetterPreference", "3"));
HttpContent content = new FormUrlEncodedContent(postData);

try
{
    var resp = httpClient.PutAsync(url, content).Result;
    return resp.Content.ReadAsStringAsync().Result;
}
catch (Exception)
{
    // Exception Handling
}

Edit job error list

Response (HTTP)	Error Type	Message
NotFound (404)	Invalid Ecruiter	"Invalid ecruiter"
NotFound (404)	Invalid Username	"Invalid ecruiter username provided."
BadRequest (400)	Invalid Job Id	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "job Id": [ "Job not found, please provide a valid job id."] } }
PreconditionFailed (412)	Model with validation errors	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "JobType": [ "Please provide a valid job type eg. Perm"] } }
Conflict (409)	Job already exists	"Job not added: This job already exists on reed.co.uk, and is not set to expire in the next 7 days."
InternalServerError (500)	Unexpected Error	"Job Api error. An error has occured the technical team have been informed."

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

var postData = new List<KeyValuePair<string, string>>();
postData.Add(new KeyValuePair<string, string>("PostingKey", @Model.ClientDetails.PostingKey));
postData.Add(new KeyValuePair<string, string>("Username", @Model.ClientDetails.Username));

HttpContent content = new FormUrlEncodedContent(postData);

try
{
    var resp = httpClient.PutAsync(url, content).Result;
    return resp.Content.ReadAsStringAsync().Result;
}
catch (Exception)
{
    // Exception Handling
}

End job error list

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid ecruiter username provided."
BadRequest (400)	Invalid Job Id	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "job Id": [ "Job not found, please provide a valid job id."] } }
PreconditionFailed (412)	Model with validation errors	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "JobType": [ "Please provide a valid job type eg. Perm"] } }
InternalServerError (500)	Unexpected Error	"Job Api error. An error has occured the technical team have been informed."

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

var postData = new List<KeyValuePair<string, string>>();
postData.Add(new KeyValuePair<string, string>("PostingKey", @Model.ClientDetails.PostingKey));
postData.Add(new KeyValuePair<string, string>("Username", @Model.ClientDetails.Username));
HttpContent content = new FormUrlEncodedContent(postData);

try
{
var resp = httpClient.PutAsync(url, content).Result;
return resp.Content.ReadAsStringAsync().Result;
}
catch (Exception)
{
}

Relist job error list

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid ecruiter username provided."
BadRequest (400)	Invalid Job Id	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "job Id": [ "Job not found, please provide a valid job id."] } }
PreconditionFailed (412)	Model with validation errors	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "JobType": [ "Please provide a valid job type eg. Perm"] } }
InternalServerError (500)	Unexpected Error	"Job Api error. An error has occured the technical team have been informed."

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

var postData = new List<KeyValuePair<string, string>>();
postData.Add(new KeyValuePair<string, string>("PostingKey", @Model.ClientDetails.PostingKey));
postData.Add(new KeyValuePair<string, string>("Username", @Model.ClientDetails.Username));
HttpContent content = new FormUrlEncodedContent(postData);

try
{
var resp = httpClient.PutAsync(url, content).Result;
return resp.Content.ReadAsStringAsync().Result;
}
catch (Exception)
{
// Exception Handling
}

Extend job error list

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid ecruiter username provided."
BadRequest (400)	Invalid Job Id	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "job Id": [ "Job not found, please provide a valid job id."] } }
PreconditionFailed (412)	Model with validation errors	JSON Serialized ModelState Object Example { "message": "The request is invalid.", "modelState": { "JobType": [ "Please provide a valid job type eg. Perm"] } }
InternalServerError (500)	Unexpected Error	"Job Api error. An error has occured the technical team have been informed."

CV Search API

Access to our CV Search API is not provided as standard. If you would like to apply for access please contact our Customer Experience team on 0845 241 9293.

Search CVs

Runs a CV search. Requires authentication. Content to be passed in the query string.

REQUEST

GET https://www.reed.co.uk/recruiter/api/1.0/cvsearch

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)
hideCandidatesWithoutSalary	boolean	If true, hides candidates without salaries (default false)
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.

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

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid token passed: You do not have permission to use this service."
BadRequest (400)	Invalid token	"Invalid ecruiter username provided."
BadRequest (400)	Bad Search Criteria	"Please refine your 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

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid ecruiter username provided."
PreconditionFailed (412)	No cv access subscription	"You don't have a valid cv access subscription."
PreconditionFailed (412)	CV not searchable	The candidate you requested is not cv searchable."
PreconditionFailed (412)	Download Limit Reached	"You have reached your daily download limit."

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

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid ecruiter username provided."
BadRequest (400)	Invalid Token	"Invalid token passed: You do not have permission to use this service."
PreconditionFailed (412)	No cv access subscription	"You don't have a valid cv access subscription."
PreconditionFailed (412)	CV not searchable	The candidate you requested is not cv searchable."
PreconditionFailed (412)	Download Limit Reached	"You have reached your daily download limit."
PreconditionFailed (412)	CV with unexpected format	"Candidate has a CV with unexpected extension."
PreconditionFailed (412)	CV with unexpected format	"CV not found for candidate: [ID]."

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

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid ecruiter username provided."
PreconditionFailed (412)	No cv access subscription	"You don't have a valid cv access subscription."
PreconditionFailed (412)	CV not searchable	The candidate you requested is not cv searchable."
PreconditionFailed (412)	Download Limit Reached	"You have reached your daily download limit."

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

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid ecruiter username provided."
PreconditionFailed (412)	No cv access subscription	"You don't have a valid cv access subscription."

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

Response (HTTP)	Error Type	Message
BadRequest (400)	Invalid Ecruiter	"Invalid ecruiter"
BadRequest (400)	Invalid Username	"Invalid token passed: You do not have permission to use this service."
BadRequest (400)	Invalid token	"Invalid ecruiter username provided."
BadRequest (400)	Bad Search Criteria	"Please refine your search"