Home page

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 statusMessage
401Your API key was invalid
403The customer's API key was invalid

API contents

Here are the functions we have developed so far:

Vacancy control

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
NameDescriptionRequiredDefaultValidationExample
titleThe title of the vacancy.YesN/AFree textSales Representative.
postcodeThe postcode of the vacancy, not displayed, used for proximity searches.YesN/AMust contain 5-10 alphanumeric characters, spaces and hyphens are allowed.AB1 2CD
locationThe location of the vacancy, for display.YesN/AFree text.Aberdeen
contractTypeThe type of employment.YesN/AOne of contract, fullTime, partTime or temporary.fullTime
salaryMinThe salary, or the lower limit of a salary range.YesN/AFree text.24,000
salaryTypeThe type of salary.YesN/AOne of year, month, day or hour.year
industry1The industry the vacancy is in.YesN/AFree text.Retail
descriptionThe complete job description of the vacancy.YesN/AFree text, HTML allowed, but only basic formatting is retained.We are looking to staff a brand new sales centre ASAP, ...
salaryMaxThe upper limit of a salary range.NoSame as salaryMinFree text, same as salaryMin by default.30,000
hideSalaryUse this to hide the salary from the vacancy listings.Nofalsetrue or false.false
additionalBenefitsAny additional benefits included in the vacancy.No(empty)Free textCompany car and private healthcare.
industry2Use this to place the vacancy in an additional industry.No(empty)Free textSales
referenceCustomer's own reference.No(empty)Free textjob00001
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
recipientEmailHave 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
recipientNameThe name of the person owning the alternative email address.No(cusomter's registered name)Free textBrian Hargreaves
vacancyTypeThe type of vacancy to list.NostandardOne of standard, featured, or promoted.standard
justTestingIndicates 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.Nofalsetrue or falsetrue

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 statusMessage
400The customer has no credits
400These required fields were missing: contractType, industry1
400These fields failed validation: postcode, contractType, vacancyType
400You must use your own API key as the customer's API key if testing your integration. (see the justTesting POST parameter)