You can either use JSON or XML. Depending on your choice of endpoint the submitted data should follow the same format. It will be the same for the returned data.
Available endpoints are following:
| XML endpoint | https://uk.whatjobs.com/api/v1/ats/{ats-name} /xml |
| JSON endpoint | https://uk.whatjobs.com/api/v1/ats/{ats-name} /json |
| Example | https://uk.whatjobs.com/api/v1/ats/your-company-name/xml |
The API access is restricted to those with an access token. This token must be passed in an HTTP custom header X-API-Token.
To retrieve your ATS name and the Authentication Token please contact us.
A request can be made to API’s Sandbox version granted that below parameter is provided in the GET request.
| Name | Required | Description |
|---|---|---|
| sandbox-mode | No | By setting this boolean parameter to true, API works in sandbox mode. e.g. sandbox-mode=true |
There is only one required HTTP POST parameter.
| Name | Required | Description |
|---|---|---|
| data | Yes | The XML or JSON attached to the body of the request. Make sure that data in the POST body matches the endpoint you’re making requests to. The table below goes into more details on what’s accepted. |
Below are the fields that can be used in the request when the command is set to add.
| Field name | Required | Type | Additional info |
|---|---|---|---|
| command | Yes | Fix | Expected value: add |
| company_email | Yes | Should be shown with this label Admin email address in the job board setting page. |
|
| company_name | Yes | String | Should be shown with this label Company name in the job board setting page. |
| company_hash | Yes | String | Should be shown with this label Hash (Optional) in the job board setting page. |
| title | Yes | String | Free text, the job title of the advert. Minimum 3 chars up to 255 chars limit. |
| description | Yes | String | Free text, from 100 to 65k chars limit, detailed job description. This field can contain the following HTML tags: p, br, b, strong, i, u, ul, li, ol
|
| job_type | Yes | SET | Acceptable values: permanent, temporary, contract |
| job_status | Yes | SET | Acceptable values: full-time, part-time |
| application_email | Yes if url is empty | Required if application_url is empty | |
| application_url | Yes if email is empty | URL | Required if application_email is empty |
| industry | No | SET | Acceptable values: Industry name, available values in the table below. |
| weeks_to_advertise | No | SET | Acceptable values: 1, 2, 3, 4, 6, 8, 10, 12 |
| salary_type | No | SET | Acceptable values: annum, month, week, day, hour |
| salary_from | No | Numeric | A float number for the lower salary. |
| salary_to | No | Numeric | A float number for the upper salary. |
| salary_currency | No | SET | Acceptable values: gbp, usd, eur |
| salary_benefits | No | String | Free text, additional salary information. |
| location | No | String | Free text, suggested format: country, region, county, town |
| postcode | No | String | Valid UK postcode. |
| reference | No | String | Free text, the job reference assigned to the advert by the recruiter. |
The table below describes the fields that can be used in the request when the command is set to delete.
| Field name | Required | Type | Additional info |
|---|---|---|---|
| command | Yes | Fix | Expected value: delete |
| company_email | Yes | Should be shown with this label Admin email address in the job board setting page. |
|
| company_name | Yes | String | Should be shown with this label Company name in the job board setting page. |
| company_hash | Yes | String | Should be shown with this label Hash (Optional) in the job board setting page. |
| job_id | Yes | String | This is the same value that will be returned in the response of add command with the following format: integer-integer |
The table below contains all valid values for the industry field.
| Industries | ||
|---|---|---|
|
|
|
<?xml version="1.0" encoding="UTF-8"?>
<job>
<command><![CDATA[add]]></command>
<company_email><![CDATA[[email protected]]]></company_email>
<company_name><![CDATA[Sample Company Name]]></company_name>
<company_hash><![CDATA[]]></company_hash>
<title><![CDATA[Sample Account Manager]]></title>
<description><![CDATA[Sample Description ...with html tag support]]></description>
<industry><![CDATA[Accountancy]]></industry>
<job_type><![CDATA[permanent]]></job_type>
<job_status><![CDATA[full-time]]></job_status>
<weeks_to_advertise><![CDATA[1]]></weeks_to_advertise>
<application_email><![CDATA[[email protected]]]></application_email>
<application_url><![CDATA[https://wwww.company.com/valid-url]]></application_url>
<salary_type><![CDATA[annum]]></salary_type>
<salary_from><![CDATA[20000]]></salary_from>
<salary_to><![CDATA[40000]]></salary_to>
<salary_currency><![CDATA[gbp]]></salary_currency>
<salary_benefits><![CDATA[Bonus payments]]></salary_benefits>
<location><![CDATA[England, Yorkshire and the Humber, Yorkshire, Hull]]></location>
<postcode><![CDATA[]]></postcode>
<reference><![CDATA[ref-123-xu]]></reference>
</job>
curl https://uk.whatjobs.com/api/v1/ats/{ats-name} /xml?sandbox-mode=true \
-X POST \
-H 'x-api-token: {Authentication-Token}' \
-d 'data=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%3Cjob%3E%3Ccommand%3E%3C!%5BCDATA%5Badd%5D%5D%3E%3C%2Fcommand%3E%3Ccompany_email%3E%3C!%5BCDATA%5Bsample%40email.com%5D%5D%3E%3C%2Fcompany_email%3E%3Ccompany_name%3E%3C!%5BCDATA%5BSample%20Company%20Name%5D%5D%3E%3C%2Fcompany_name%3E%3Ccompany_hash%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fcompany_hash%3E%3Ctitle%3E%3C!%5BCDATA%5BSample%20Account%20Manager%5D%5D%3E%3C%2Ftitle%3E%3Cdescription%3E%3C!%5BCDATA%5BSample%20Description%20...with%20html%20tag%20support%5D%5D%3E%3C%2Fdescription%3E%3Cindustry%3E%3C!%5BCDATA%5BAccountancy%5D%5D%3E%3C%2Findustry%3E%3Cjob_type%3E%3C!%5BCDATA%5Bpermanent%5D%5D%3E%3C%2Fjob_type%3E%3Cjob_status%3E%3C!%5BCDATA%5Bfull-time%5D%5D%3E%3C%2Fjob_status%3E%3Cweeks_to_advertise%3E%3C!%5BCDATA%5B1%5D%5D%3E%3C%2Fweeks_to_advertise%3E%3Capplication_email%3E%3C!%5BCDATA%5Bvalid-email-address%40company.com%5D%5D%3E%3C%2Fapplication_email%3E%3Capplication_url%3E%3C!%5BCDATA%5Bhttps%3A%2F%2Fwwww.company.com%2Fvalid-url%5D%5D%3E%3C%2Fapplication_url%3E%3Csalary_type%3E%3C!%5BCDATA%5Bannum%5D%5D%3E%3C%2Fsalary_type%3E%3Csalary_from%3E%3C!%5BCDATA%5B20000%5D%5D%3E%3C%2Fsalary_from%3E%3Csalary_to%3E%3C!%5BCDATA%5B40000%5D%5D%3E%3C%2Fsalary_to%3E%3Csalary_currency%3E%3C!%5BCDATA%5Bgbp%5D%5D%3E%3C%2Fsalary_currency%3E%3Csalary_benefits%3E%3C!%5BCDATA%5BBonus%20payments%5D%5D%3E%3C%2Fsalary_benefits%3E%3Clocation%3E%3C!%5BCDATA%5BEngland%2C%20Yorkshire%20and%20the%20Humber%2C%20Yorkshire%2C%20Hull%5D%5D%3E%3C%2Flocation%3E%3Cpostcode%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fpostcode%3E%3Creference%3E%3C!%5BCDATA%5Bref-123-xu%5D%5D%3E%3C%2Freference%3E%3C%2Fjob%3E'
<?xml version="1.0" encoding="UTF-8"?>
<job>
<command><![CDATA[delete]]></command>
<company_email><![CDATA[[email protected]]]></company_email>
<company_name><![CDATA[Sample Company Name]]></company_name>
<company_hash><![CDATA[]]></company_hash>
<job_id><![CDATA[185394403-1508429206]]></job_id>
</job>
curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/xml?sandbox-mode=true \
-X POST \
-H 'x-api-token: {Authentication-Token}' \
-d 'data=%3C%3Fxml%20version%3D%221.0%22%20encoding%3D%22UTF-8%22%3F%3E%3Cjob%3E%3Ccommand%3E%3C!%5BCDATA%5Bdelete%5D%5D%3E%3C%2Fcommand%3E%3Ccompany_email%3E%3C!%5BCDATA%5Bsample%40email.com%5D%5D%3E%3C%2Fcompany_email%3E%3Ccompany_name%3E%3C!%5BCDATA%5BSample%20Company%20Name%5D%5D%3E%3C%2Fcompany_name%3E%3Ccompany_hash%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Fcompany_hash%3E%3Cjob_id%3E%3C!%5BCDATA%5B185394403-1508429206%5D%5D%3E%3C%2Fjob_id%3E%3C%2Fjob%3E'
{
"command": "add",
"company_email": "[email protected]",
"company_name": "Sample Company Name",
"company_hash": "",
"title": "Sample Account Manager",
"description": "Sample Description ...with html tag support",
"industry": "Accountancy",
"job_type": "permanent",
"job_status": "full-time",
"weeks_to_advertise": "1",
"application_email": "[email protected]",
"application_url": "https://wwww.company.com/valid-url",
"salary_type": "annum",
"salary_from": "20000",
"salary_to": "40000",
"salary_currency": "gbp",
"salary_benefits": "Bonus payments",
"location": "England, Yorkshire and the Humber, Yorkshire, Hull",
"reference": "ref-123-xu"
}
curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/json?sandbox-mode=true \
-X POST \
-H 'x-api-token: {Authentication-Token}' \
-d 'data=%7B%22command%22%3A%22add%22%2C%22company_email%22%3A%22sample%40email.com%22%2C%22company_name%22%3A%22Sample%20Company%20Name%22%2C%22company_hash%22%3A%22%22%2C%22title%22%3A%22Sample%20Account%20Manager%22%2C%22description%22%3A%22Sample%20Description%20...with%20html%20tag%20support%22%2C%22industry%22%3A%22Accountancy%22%2C%22job_type%22%3A%22permanent%22%2C%22job_status%22%3A%22full-time%22%2C%22weeks_to_advertise%22%3A%221%22%2C%22application_email%22%3A%22valid-email-address%40company.com%22%2C%22application_url%22%3A%22https%3A%2F%2Fwwww.company.com%2Fvalid-url%22%2C%22salary_type%22%3A%22annum%22%2C%22salary_from%22%3A%2220000%22%2C%22salary_to%22%3A%2240000%22%2C%22salary_currency%22%3A%22gbp%22%2C%22salary_benefits%22%3A%22Bonus%20payments%22%2C%22location%22%3A%22England%2C%20Yorkshire%20and%20the%20Humber%2C%20Yorkshire%2C%20Hull%22%2C%22reference%22%3A%22ref-123-xu%22%7D'
{
"command": "delete",
"company_email": "[email protected]",
"company_name": "Sample Company Name",
"company_hash": "",
"job_id": "185394403-1508429206"
}
curl https://uk.whatjobs.com/api/v1/ats/{ats-name}/json?sandbox-mode=true \
-X POST \
-H 'x-api-token: {Authentication-Token}' \
-d 'data=%7B%22command%22%3A%20%22delete%22%2C%20%22company_email%22%3A%20%22sample%40email.com%22%2C%20%22company_name%22%3A%20%22Sample%20Company%20Name%22%2C%20%22company_hash%22%3A%20%22%22%2C%20%22job_id%22%3A%20%22185394403-1508429206%22%7D'
Depending on action’s result the returned HTTP status code can be one of the values below.
| Status Code | Reason | Returned message addressee | Description |
|---|---|---|---|
| 200 | Success | End user | This is the result of a successful action and the returned message variable value should be shown to the end user. |
| 203 | Error in the user data | End user | This happens each time the end user enters invalid information. The returned message should be shown to the user. For example, when a user enters an invalid email address or doesn't have sufficient credit. |
| 400 | Bug in the ATS configuration | ATS | It means there was an issue in the submitted data structure. This happens when there is a bug in the ATS configuration. For example, the value of command parameter is something other than add or delete, or the value of the weeks_to_advertise parameter is out of bounds. The reason can be found in the returned message variable. |
| 503 | API Error | ATS | The API is temporary unavailable and could not handle the request for a while. The returned message provides more information. In this case, the returned result can be an HTML. |
The returned response will be XML or JSON depends on the selected endpoint. All responses will contain the variables below.
| Name | Description |
|---|---|
| success | A boolean value indicates the status of the returned response which can be True (With the HTTP code of 200) or False (With the HTTP code of 203, 400 or 503). |
| message | The returned message should be shown to the end user when HTTP code is either 200 or 203. |
| job_url | It contains the job URL on successful add command execution and null otherwise. |
| job_id | Contains the job id on successful add command execution and null otherwise. This id should be provided on delete command. |
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<success><![CDATA[true]]></success>
<message><![CDATA[The job has been added successfully.]]></message>
<job_url><![CDATA[https://uk.whatjobs.com/job/sample-job-example-url]]></job_url>
<job_id><![CDATA[185394449-1508749660]]></job_id>
</response>
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<success><![CDATA[true]]></success>
<message><![CDATA[The job has been deleted successfully.]]></message>
<job_url><![CDATA[]]></job_url>
<job_id><![CDATA[]]></job_id>
</response>
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<success><![CDATA[false]]></success>
<message><![CDATA[The company email must be a valid email address.]]></message>
<job_url><![CDATA[]]></job_url>
<job_id><![CDATA[]]></job_id>
</response>
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<success><![CDATA[false]]></success>
<message><![CDATA[The submitted data is corrupted.]]></message>
<job_url><![CDATA[]]></job_url>
<job_id><![CDATA[]]></job_id>
</response>
{
"success": true,
"message": "The job has been added successfully.",
"job_url": "https://uk.whatjobs.com/job/sample-job-example-url",
"job_id": "185394449-1508749660"
}
{
"success": true,
"message": "The job has been deleted successfully.",
"job_url": null,
"job_id": null
}
{
"success": false,
"message": "The company email must be a valid email address.",
"job_url": null,
"job_id": null
}
{
"success": false,
"message": "The submitted data is corrupted.",
"job_url": null,
"job_id": null
}
Depending on the application method when a user applies for a job, we will either use application_email or application_url to send the applicant's details to ATS by email; or redirect the user to the provided URL. If both variables values are available, the default method used will be the application by email.
The application mail will be sent from a uniquely generated email address to the given application email address, with following subject Application for {job-title} - {job-reference}.
The email also contains the reply-to header with the end user’s email address.
The email body contains HTML and plain text versions. Both versions contain the fields explained below. HTML tags format the HTML version, and the text version is in JSON format.
| Field name | Description |
|---|---|
| job_title | Job title |
| job_reference | Job reference, if provided. |
| first_name | Job seeker first name |
| last_name | Job seeker Surname |
| email_address | Job seeker email address |
| covering_letter | The covering letter, if provided. |