API Quick start

Overview

The Reach ATS® API has been designed to provide an easy to use toolkit for adding recruitment related data into your career web pages or backoffice systems.

The API is REST based and can be called from many modern languages such as PHP, Python,classic ASP, ASP.net, Perl and Java.

Accessing the API

The API is available from the following URL : http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/

You will note that the API key (in bold) is used as part of the URL itself. For the purposes of testing, the key above may be used to generate ficticious data for testing.

Default Call Example (XML)

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/listing/

N.B. (View source in the browser, as by default this call outputs XML)

Output Example

	
<response generated="2011-06-30T16:48:07+01:00" records="3">
	<record>
		<id><![CDATA[25618]]></id>
		<title><![CDATA[Assistant Store Manager - Camden]]></title>
		<category><![CDATA[Sales]]></category>
		<role><![CDATA[Sales]]></role>
		<type><![CDATA[Permanent]]></type>
		<hours><![CDATA[35]]></hours>
		<salarydescription><![CDATA[25,000]]></salarydescription>
		<closingdate><![CDATA[2013-01-04]]></closingdate>
	</record>
</response>
		

JSON Call Example

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/listing/-/-/-/-/JSON


Anatomy of a request

The API call above returns an XML document with the job information for jobs that are currently live. Each call has the following structure:

Action

/get/job/advert/12345/JSON


The first segment of the request is an action verb. Most of the time, you will use get, however others are available.

Package

/get/job/advert/12345/JSON


The second segment of the request specifies the package that your information call is related to.

Data

/get/job/advert/12345/JSON


The third segment of the request specifies the information that you are calling from the preceding module in the second segment. In the example above we are requesting the advert text from the job module, therefore the "Job Advert".

Parameters

/get/job/advert/12345/JSON


After the first three segments, any data that is required by a specific call needs to be placed after them. Each variable is separated by a slash, and details on how many each requires are given in each of the call's documentation below. If you need to mark a certain requirement in the URL as undefined, use a hyphen, E.G. /get/job/listing/-/JSON. In this example, a hyphen is used to specify no search terms are required (that is, the field is blank), so that the return type of JSON can be specified at the right url position.

Data type of response

/get/job/advert12345/JSON


The last part of a request is optional, and denotes which return data type you would like. Each API call by default returns one of several data types, depending on it's purpose. For example, by default job listings are in XML, however a job advert is returned as raw text, with no metadata or delimiters. Each call description in the documentation will give it's default response type.

Available Data Types for Results

The data type you require if set MUST be in capital letters at the end of the URL.



Sample Packages

A package is simply a grouping of calls for a certain type, for example all job related calls are grouped into a package called job, all account based calls into account, and so forth.

Job

This package contains the following calls:

listing (Default datatype XML. 5 Optional Arguments: Keyword, Location, Type, Role, Encoding))

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/listing/

/get/job/listing returns the records for all live jobs on the associated account, including the job's ID, title, category, role,type, hours, salary description and closing date. It optionally accepts one argument, to specific keywords to match the job title to, location and role. This is useful if you would like to implement a search feature, without having to write your own mechanism. If you wish to provide a data return type, but omit optional variables, replace the segment of the url with a hyphen, E.G /get/job/listing/-/-/-/-/JSON.
Parameter Order:

/get/job/listing/KEYWORDS/LOCATION/TYPE/ROLE/ENCODING

Where:
  • Keywords = specific words in Job Title, e.g. Assistant
  • Location = Town job is located in, e.g. Bromsgrove
  • Type = Job Type, e.g. Permenant, Full Time etc.
  • Role = Job Role, e.g. Administrator

listingByPostcode (Default datatype XML. 2 Required Arguments: Postcode, Range. 5 Optional Arguments: Keyword, Location, Type, Role, Encoding)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/listingByPostcode/B610GD/25/-/-/-/-/JSON

/get/job/listingByPostcode returns the records for all live jobs on the associated account within a postcode radius, including the job's ID, title, category, role,type, hours, salary description and closing date. It requires Postcode and Range at a minimum. It optionally accepts 3 arguments, to specific keywords to match the job title to, location and role. This is useful if you would like to implement a search feature, without having to write your own mechanism. If you wish to provide a data return type, but omit optional variables, replace the segment of the url with a hyphen, E.G /get/job/listingByPostcode/B610GD/25/-/-/-/-/JSON.
Parameter Order:

/get/job/listingByPostcode/POSTCODE/RANGE/KEYWORDS/LOCATION/TYPE/ROLE/ENCODING

information (Default datatype XML. 1 Required Argument : Job ID)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/information/25645

/get/job/information returns the job listing information for a specific job only. By default, the call supplies the data as XML. The call has one argument, being the JOB ID of the job that you want the details for.

advert (Alias: text. Default datatype RAW. 1 Required Argument : Job ID)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/advert/25626

/get/job/advert returns the advert text for a job in HTML. By default, the call supplies the data as is. The call has one argument, being the JOB ID of the job that you want the text for. (The job ID is more than likely taken from a previous call to /job/listing).

N.B. If you're using a client-side framework to get the data (such as React), you may encounter Ad-Blocking issues with this call, due to the word "advert". In this case you can use the alias "text". e.g.
http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/text/25626


applyurl (Default datatype RAW. 1 Required Argument : Job ID)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/applyurl/25626

/get/job/applyurl returns the url to the job's application process. By default, the call supplies the data as is. The call has one argument, being the JOB ID of the job that you want the url for.

fileurls (Default datatype XML. 1 Required Argument : Job ID)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/fileurls/25645

/get/job/fileurls returns the urls to the job's support files, along with a friendly name for on screen. By default, the call supplies the data as XML. The call has one argument, being the JOB ID of the job that you want the file urls for.



Listing Data

A list simply returns all the values for the account that is set up in the ATS. Useful for populating elements such as select boxes.

Locations (Default datatype JSON)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/locations

/get/job/locations returns a unique set of locations for the account

Counties (Default datatype JSON)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/counties

/get/job/counties returns a unique set of counties for the account

Roles (Default datatype JSON)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/roles

/get/job/roles returns a unique set of roles for the account

Offices (Default datatype JSON)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/offices

/get/job/offices returns a unique set of offices for the account

Types (Default datatype JSON)

Example:

http://a83d66d29041c407e8abf4187c533053.api.instinctivetechnologies.com/get/job/types

/get/job/types returns a unique set of types for the account


PHP Examples

For the purpose of these examples we'll be assuming some default variables are set:

$key = "a83d66d29041c407e8abf4187c533053";
$apiUrl = "api.instinctivetechnologies.com";

Retrieve all jobs listing data

	
function jobListing($key,$apiUrl) {

	//set variables
	$fullApiUrl = "http://".$key.".".$apiUrl;
	$output = "";

	//Retrieve and parse the job data from the ATS server in JSON format
	$parsedJobData = json_decode(@file_get_contents($fullApiUrl."/get/job/listing/-/-/-/-/JSON"));

	// if there are no live vacancies
	if(empty($parsedJobData)) {
		// Replace this with your preferred code/message & styling
		$output = "Unfortunately there are no current vacancies at this time";
	}else{
		//For each job published to the career site
		foreach($parsedJobData as $job){
			//Get the advert text to create a lead line
			$advertText = @file_get_contents($fullApiUrl."/get/job/advert/$job->id");

			/* Put your styled content here as you normally would. */
			$output .= "$job->title - $job->location<br/>
						Salary - $job->salarydescription<br/><br/>";

			// This adds an excerpt to the end of the job information
			// providing a lead in to the full advert
			$output .= substr($advertText,0,200)," ... <br/>";
			/* end styled content */
		}
	}

	return $output;
}

echo jobListing($key,$apiUrl);

Retrieve advert text for specific job

$fullApiUrl = "http://".$key.".".$apiUrl;
$advertText = @file_get_contents($fullApiUrl."/get/job/advert/JOB_ID");