Anatomy of a request

Each request is constructed from five segments:

1. Action — usually get.
2. Package — the module you are querying, e.g. job.
3. Data — the resource within that package, e.g. listing or advert.
4. Parameters — positional arguments separated by slashes. Use a hyphen (-) for empty values.
5. Response type (Encoding) (optional) — override the default format with XML, JSON, CSV, PIPE or RAW. This is always the last parameter of the URL.

Example: /get/job/listing/-/-/-/-/JSON fetches the job listing, skips optional filters, and requests JSON.

Job package endpoints

• listing — returns all live vacancies with optional keyword, location, type, role and encoding arguments.
• listingByPostcode — adds mandatory postcode and range parameters for radius-based searches.
• information — fetches a single vacancy record by job ID, including contact and workflow data.
• advert (alias text or description) — returns the full advert copy in RAW format.
• applyurl / applyurlsource / applysource — resolve application URLs for external or internal sources.
• fileurls — lists downloadable assets tied to the vacancy.

Listing variations

Job details & media

Job metadata (similar to the new Lists API below)

Core list endpoints

Live-only variants

Use the live_* endpoints to limit filter options to values that have active vacancies.

Organisation lookups

Pre-built alert experience

Reach ships a responsive HTML page for job alert sign-up. Embed it inside an iframe or surface it within a modal/popup to collect alert registrations.

It may be possible for us to create a bespoke sign up template for you mimicing your branding styles, please let us know if this is something you require.

Alert embed endpoints

The Jobalert module exposes helper routes for pre-built signup forms that you can iFrame or load in a modal. Swap the rows, version, client, or group parameters as needed.

A basic API class implemented to display & filter vacancies (JSON)

<?php
class ReachApiClient {
	private string $host;

	public function __construct(private readonly string $apiKey) {
		$this->host = sprintf('https://%s.reach-ats.com', $apiKey);
	}

	public function get(string $path): string {
		$url = $this->host . $path;

		if (ini_get('allow_url_fopen')) {
			$response = @file_get_contents($url);
		} elseif (function_exists('curl_init')) {
			$curl = curl_init($url);
			curl_setopt_array($curl, [
				CURLOPT_RETURNTRANSFER => true,
				CURLOPT_CONNECTTIMEOUT => 5,
				CURLOPT_TIMEOUT => 10,
			]);
			$response = curl_exec($curl);
			curl_close($curl);
		} else {
			throw new RuntimeException('Unable to fetch data; enable allow_url_fopen or install cURL.');
		}

		if ($response === false) {
			throw new RuntimeException("Reach ATS request failed for {$url}");
		}

		return $response;
	}

	public function getJson(string $path): array {
		return json_decode($this->get($path), true, 512, JSON_THROW_ON_ERROR);
	}

	public static function renderOptions(array $values, ?string $selected = null): string {
		$items = array_unique(array_filter(array_map('strval', $values)));
		sort($items, SORT_NATURAL | SORT_FLAG_CASE);

		return implode('', array_map(static function (string $value) use ($selected): string {
			$isSelected = $selected !== null && strcasecmp($selected, $value) === 0;
			return sprintf(
				'<option value="%s"%s>%s</option>',
				rawurlencode($value),
				$isSelected ? ' selected' : '',
				htmlspecialchars($value, ENT_QUOTES, 'UTF-8')
			);
		}, $items));
	}

	public function listing(
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/listing/', [
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function listingByPostcode(
		string $postcode,
		string $range,
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/listingByPostcode/', [
			$postcode,
			$range,
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function listingBySource(
		string $sources,
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/listingBySource/', [
			$sources,
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function listingBySourceAndPostcode(
		string $sources,
		string $postcode,
		string $range,
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/listingBySourceAndPostcode/', [
			$sources,
			$postcode,
			$range,
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function internalListing(
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/internalListing/', [
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function internalListingByPostcode(
		string $postcode,
		string $range,
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/internalListingByPostcode/', [
			$postcode,
			$range,
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function internalListingBySource(
		string $sources,
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/internalListingBySource/', [
			$sources,
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function internalListingBySourceAndPostcode(
		string $sources,
		string $postcode,
		string $range,
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/internalListingBySourceAndPostcode/', [
			$sources,
			$postcode,
			$range,
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function listingByCounty(
		string $keywords = '-',
		string $county = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/listingCounty/', [
			$keywords,
			$county,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function referralListing(
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/referralListing/', [
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function speculativeListing(
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/speculativeListing/', [
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function openDayListing(
		string $keywords = '-',
		string $location = '-',
		string $type = '-',
		string $role = '-',
		string $encoding = 'JSON'
	): array {
		return $this->getJson($this->buildPath('/get/job/openDayListing/', [
			$keywords,
			$location,
			$type,
			$role,
			$this->formatEncoding($encoding),
		]));
	}

	public function jobInformation(int|string $jobId, string $encoding = 'JSON'): array {
		return $this->getJson($this->buildPath('/get/job/information/', [
			$jobId,
			$this->formatEncoding($encoding),
		]));
	}

	public function jobAdvert(int|string $jobId): string {
		return $this->get($this->buildPath('/get/job/advert/', [$jobId]));
	}

	public function jobFileUrls(int|string $jobId, string $encoding = 'JSON'): array {
		return $this->getJson($this->buildPath('/get/job/fileurls/', [
			$jobId,
			$this->formatEncoding($encoding),
		]));
	}

	private function buildPath(string $prefix, array $segments): string {
		return $prefix . implode('/', array_map([$this, 'segment'], $segments));
	}

	private function segment(null|int|string $value): string {
		if ($value === null || $value === '') {
			return '-';
		}
		if ($value === '-') {
			return '-';
		}
		return rawurlencode((string) $value);
	}

	private function formatEncoding(?string $encoding): string {
		return strtoupper($encoding ?? 'JSON');
	}
}

$client = new ReachApiClient('a83d66d29041c407e8abf4187c533053');

$listing = $client->listing();

// Apply simple, client-side filtering beyond the API segments.
$filters = [
	'division' => $_GET['division'] ?? null,
	'officename' => $_GET['officename'] ?? null,
	'hours' => $_GET['hours'] ?? null,
	'role' => $_GET['role'] ?? null,
];

$filtered = array_filter($listing, static function (array $job) use ($filters): bool {
	foreach ($filters as $key => $value) {
		if ($value === null || $value === '') {
			continue;
		}
		if (!isset($job[$key]) || strcasecmp($job[$key], $value) !== 0) {
			return false;
		}
	}
	return true;
});

$options = [
	'division' => ReachApiClient::renderOptions(array_column($listing, 'division'), $filters['division']),
	'officename' => ReachApiClient::renderOptions(array_column($listing, 'officename'), $filters['officename']),
	'hours' => ReachApiClient::renderOptions(array_column($listing, 'hours'), $filters['hours']),
	'role' => ReachApiClient::renderOptions(array_column($listing, 'role'), $filters['role']),
];

?>

<form method="get" action="">
	<label>
		Division
		<select name="division" onchange="this.form.submit()">
			<option value="">All divisions</option>
			<?= $options['division']; ?>
		</select>
	</label>
	<label>
		Office
		<select name="officename" onchange="this.form.submit()">
			<option value="">All offices</option>
			<?= $options['officename']; ?>
		</select>
	</label>
	<label>
		Role
		<select name="role" onchange="this.form.submit()">
			<option value="">All roles</option>
			<?= $options['role']; ?>
		</select>
	</label>
	<label>
		Hours
		<select name="hours" onchange="this.form.submit()">
			<option value="">Any hours</option>
			<?= $options['hours']; ?>
		</select>
	</label>
	<noscript><button type="submit">Apply filters</button></noscript>
</form>

<p>Showing <strong><?= count($filtered); ?></strong> of <strong><?= count($listing); ?></strong> vacancies.</p>

<?php foreach ($filtered as $job): ?>
	<?php
		$jobId = $job['id'];
		$job = $client->jobInformation($jobId);
		$advertHtml = $client->jobAdvert($jobId);
		$attachments = $client->jobFileUrls($jobId);
	?>
	<section class="vacancy-summary">
		<h3><?= htmlspecialchars($job['title'], ENT_QUOTES, 'UTF-8'); ?></h3>
		<div class="vacancy-advert"><?= $advertHtml; ?></div>
		<?php if (!empty($attachments)): ?>
			<h4>Attachments</h4>
			<ul>
				<?php foreach ($attachments as $file): ?>
					<li>
						<a href="<?= htmlspecialchars($file['url'] ?? '#', ENT_QUOTES, 'UTF-8'); ?>" target="_blank">
							<?= htmlspecialchars($file['type'] ?? 'Download', ENT_QUOTES, 'UTF-8'); ?>
						</a>
					</li>
				<?php endforeach; ?>
			</ul>
		<?php endif; ?>
	</section>
<?php endforeach; ?>
?>

Fetch detail including advert text and files for a specific vacancy

<?php
try {
	$client = new ReachApiClient('a83d66d29041c407e8abf4187c533053');
	$jobId = 129436;
	$information = $client->jobInformation($jobId);
	$advertHtml = $client->jobAdvert($jobId);
	$fileAttachments = $client->jobFileUrls($jobId);
} catch (Throwable $exception) {
	error_log($exception->getMessage());
	// Handle gracefully (show fallback message, etc.)
}

if (!empty($information)) {
	$vacancy = $information[0];
	echo '<h3>' . htmlspecialchars($vacancy['title'] ?? 'Vacancy', ENT_QUOTES, 'UTF-8') . '</h3>';
	echo $advertHtml; // Already HTML

	if (!empty($fileAttachments)) {
		echo '<h4>Supporting documents</h4><ul>';
		foreach ($fileAttachments as $file) {
			$label = htmlspecialchars($file['type'] ?? 'Download', ENT_QUOTES, 'UTF-8');
			$url = htmlspecialchars($file['url'] ?? '#', ENT_QUOTES, 'UTF-8');
			echo '<li><a href="' . $url . '" target="_blank">' . $label . '</a></li>';
		}
		echo '</ul>';
	}
}