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:


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:


Error responses

All API error responses are in the following format:


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:



Create a vacancy request parameters
titleThe title of the vacancy.YesFree text.
postcodeThe postcode of the vacancy, not displayed, used for proximity searches.YesMust contain 5-10 alphanumeric characters, spaces and hyphens are allowed.
locationThe location of the vacancy, for display.YesFree text.
contractTypeThe type of employment, full time, for example.YesOne of contract, fullTime, partTime or temporary.
salaryMinThe salary, or the lower limit of a salary range.YesFree text.
salaryTypeThe type of salary, per annum, for example.YesOne of year, month, day or hour.
industry1The industry the vacancy is in, accounting, for example.YesFree text.
descriptionThe complete job description of the vacancy.YesFree text, HTML allowed, but only basic formatting is retained.
salaryMaxThe upper limit of a salary range.NoFree text, same as salaryMin by default.
hideSalaryUse this to hide the salary from the vacancy listings.Notrue or false. Empty is also false.
additionalBenefitsAny additional benefits included in the vacancy.NoFree text, empty by default.
industry2Use this to place the vacancy in an additional industry.NoFree text, empty by default.
referenceCustomer's own reference, job00001, for example.NoFree text, empty by default.
Up to 5 statements that candidates must agree with before they can apply for the vacancy.NoFree 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?".
recipientEmailHave the candidate applications emailed to an alternative email address.NoEmail address. Customer's registered email by default.
recipientNameThe name of the person owning the alternative email address.NoFree text. Customer's registered name by default.
vacancyTypeThe type of vacancy to list.NoOne of standard, featured, or promoted. standard by default.
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.Notrue or false. Empty is also false.

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:


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)