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.
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.
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.
All character encoding must be UTF-8, using the API with other encodings may cause undesirable results.
We have decided to use
application/x-www-form-urlencoded because this content type has the widest support.
We may develop support for
application/xml in future, if there is sufficient demand.
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:
All API error responses are in the following format:
Here are the messages that can occur for any API call:
|401||Your API key was invalid|
|403||The customer's API key was invalid|
Here are the functions we have developed so far:
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:
|The title of the vacancy.||Yes||N/A||Free text||Sales Representative.|
|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|
|The location of the vacancy, for display.||Yes||N/A||Free text.||Aberdeen|
|The type of employment.||Yes||N/A||One of ||fullTime|
|The salary, or the lower limit of a salary range.||Yes||N/A||Free text.||24,000|
|The type of salary.||Yes||N/A||One of ||year|
|The industry the vacancy is in.||Yes||N/A||Free text.||Retail|
|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, ...|
|The upper limit of a salary range.||No||Same as ||Free text, same as ||30,000|
|Use this to hide the salary from the vacancy listings.||No||false|
|Any additional benefits included in the vacancy.||No||(empty)||Free text||Company car and private healthcare.|
|Use this to place the vacancy in an additional industry.||No||(empty)||Free text||Sales|
|Customer's own reference.||No||(empty)||Free text||job00001|
|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|
|Have the candidate applications emailed to an alternative email address.||No||(customer's registered email address)||Email address to receive application firstname.lastname@example.org|
|The name of the person owning the alternative email address.||No||(cusomter's registered name)||Free text||Brian Hargreaves|
|The type of vacancy to list.||No||One of ||standard|
|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||true|
If successful, the response will be HTTP 200 and the body will contain the ID and URL of the new vacancy, using
|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 |