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:
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
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
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
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)
|