The Job Matrix API

The Job Matrix API is an Application Programming Interface for software developers to enable their applications to communicate with The Job Matrix.

This means you can potentially use The Job Matrix website indirectly, for example, with desktop software, a mobile application, or another website.

API Keys

Instead of handing out your username and password to other systems, you need to provide them with your API Key. Your API Key identifies you and must be treated just as personally as your account login details.

You need to log in to see your API Key

The rest of this page contains technical information for software developers.

Developer documentation

The Job Matrix API uses two API Keys, one to identify the software developer and another belonging to the user of the software.

Software developers therefore need to create an account and use their API Key to indicate who to contact as the software developer using the API.

If you are a customer developing your own software, using the same API Key to identify yourself as the software developer and the user of your software is no problem.

General information

Character encoding

All character encoding must be UTF-8, using the API with other encodings may cause undesirable results.

Content type

We have decided to use application/x-www-form-urlencoded because this content type has the widest support.

We may develop support for application/json and application/xml in future, if there is sufficient demand.

API reference

The API is hosted at:

https://jobmatrix.co.uk/api/{API_KEY}

You will also need the API Keys of all your customers. The customer's API Key is always the next element of the URL path, like this:

https://jobmatrix.co.uk/api/{API_KEY}/{CUSTOMER_API_KEY}

Error responses

All API error responses are in the following format:

error={ERROR_MESSAGE}

Here are the messages that can occur for any API call:

General error messages
HTTP status	Message
401	Your API key was invalid
403	The customer's API key was invalid

API contents

Here are the functions we have developed so far:

Vacancy control

Create a vacancy

If you require a function not listed here, please contact us to let us know.

Create a vacancy

Send your vacancy details in a HTTP POST request to:

https://jobmatrix.co.uk/api/{API_KEY}/{CUSTOMER_API_KEY}/create-vacancy

Parameters

Create a vacancy request parameters
Name	Description	Required	Default	Validation	Example
`title`	The title of the vacancy.	Yes	N/A	Free text	Sales Representative.
`postcode`	The postcode of the vacancy, not displayed, used for proximity searches.	Yes	N/A	Must contain 5-10 alphanumeric characters, spaces and hyphens are allowed.	AB1 2CD
`location`	The location of the vacancy, for display.	Yes	N/A	Free text.	Aberdeen
`contractType`	The type of employment.	Yes	N/A	One of `contract`, `fullTime`, `partTime` or `temporary`.	fullTime
`salaryMin`	The salary, or the lower limit of a salary range.	Yes	N/A	Free text.	24,000
`salaryType`	The type of salary.	Yes	N/A	One of `year`, `month`, `day` or `hour`.	year
`industry1`	The industry the vacancy is in.	Yes	N/A	Free text.	Retail
`description`	The complete job description of the vacancy.	Yes	N/A	Free text, HTML allowed, but only basic formatting is retained.	We are looking to staff a brand new sales centre ASAP, ...
`salaryMax`	The upper limit of a salary range.	No	Same as `salaryMin`	Free text, same as `salaryMin` by default.	30,000
`hideSalary`	Use this to hide the salary from the vacancy listings.	No	`false`	`true` or `false`.	false
`additionalBenefits`	Any additional benefits included in the vacancy.	No	(empty)	Free text	Company car and private healthcare.
`industry2`	Use this to place the vacancy in an additional industry.	No	(empty)	Free text	Sales
`reference`	Customer's own reference.	No	(empty)	Free text	job00001
`screeningQuestion1` `screeningQuestion2` `screeningQuestion3` `screeningQuestion4` `screeningQuestion5`	Up to 5 statements that candidates must agree with before they can apply for the vacancy.	No	(no screening questions)	Free text, better when phrased as a statement than a question. For example "I hold a full UK driving licence" and not "Do you own a full UK driving licence?".	I hold a full UK driving licence
`recipientEmail`	Have the candidate applications emailed to an alternative email address.	No	(customer's registered email address)	Email address to receive application notifications.	b.hargreaves@example.com
`recipientName`	The name of the person owning the alternative email address.	No	(cusomter's registered name)	Free text	Brian Hargreaves
`vacancyType`	The type of vacancy to list.	No	`standard`	One of `standard`, `featured`, or `promoted`.	standard
`justTesting`	Indicates that the vacancy is just a test, the vacancy will be publicly listed, but it and any associated candidate information will be permanently deleted after 30 minutes, your account will not be deducted any credits.	No	`false`	`true` or `false`	true

Success response

If successful, the response will be HTTP 200 and the body will contain the ID and URL of the new vacancy, using application/x-www-form-urlencoded encoding:

id={VACANCY_ID}&url=https%3A%2F%2Fthejobmatrix.co.uk%2Fvacancy%2F{VACANCY_ID}

Error response

Create a vacancy error messages
HTTP status	Message
400	The customer has no credits
400	These required fields were missing: contractType, industry1
400	These fields failed validation: postcode, contractType, vacancyType
400	You must use your own API key as the customer's API key if testing your integration. (see the `justTesting` POST parameter)