Multi-posting (ATS)

Solution API Technical Guide

ATS Integration Documentation.

This document will guide you through the ATS API integration details and implementation process. WhatJobs provides an easy to use API allowing job posters to send the requests to REST interface. The API accepts POST requests which means that any software you write to interact with ATS API must make POST request.

  Request and Response Formats  


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
 

  Token-based Authentication  


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.

 

  HTTP Request Parameters  


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.
 

  XML/JSON Data Fields  


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 Email 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 Email 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 Email 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
 

  Accepted Industry Values  


The table below contains all valid values for the industry field.

Industries
  • Accountancy
  • Administration and Secretarial
  • Aerospace and Aviation
  • Agriculture Fishing, Forestry and Conservation
  • Automotive
  • Banking and Financial Services
  • Catering and Hospitality
  • Charity and Voluntary
  • Construction and Property
  • Customer Service
  • Defence and Military
  • Driving and Transport
  • Education and Training
  • Electronics
  • Energy, Utilities, Oil and Gas
  • Engineering
  • Fashion and Arts
  • FMCG
  • Graduates and Trainees
  • Health, Security and Safety
  • Healthcare and Medical
  • Human Resources and Personnel
  • Information Technology
  • Insurance
  • Journalism, Publishing and Translation
  • Legal
  • Leisure, Tourism and Entertainment
  • Logistics and Warehousing
  • Management and Consultancy
  • Manufacturing and Production
  • Marketing, Advertising and PR
  • Media, Design and Creative
  • Personal Assistant
  • Pharmaceutical
  • Public Sector and Government
  • Purchasing and Procurement
  • Recruitment
  • Retail and Wholesale
  • Sales
  • Scientific
  • Social Care
  • Telecommunications
 

  Valid XML Request example  


 
XML Sample for Add Command
          <?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>
 
XML cURL Sample for Add Command
            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 Sample for Delete Command
            <?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>
          
 
XML cURL Sample for Delete Command
            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'
          
 
JSON Sample for Add Command
            {
              "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"
            }
 
JSON cURL Sample for Add Command
              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'
            
 
JSON Sample for Delete Command
              {
                "command": "delete",
                "company_email": "[email protected]",
                "company_name": "Sample Company Name",
                "company_hash": "",
                "job_id": "185394403-1508429206"
              }
 
JSON cURL Sample for Delete Command
                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'
              
 

  HTTP Response Status Codes  


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.
 

  Response Format  


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.
 

  Sample Responses  


 
XML success response with HTTP code of 200
                <?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 success response with HTTP code of 200
                <?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 error response with HTTP code of 203
                  <?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 error response with HTTP code of 400
                  <?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>
 
JSON success response with HTTP code of 200
                    {
                      "success": true,
                      "message": "The job has been added successfully.",
                      "job_url": "https://uk.whatjobs.com/job/sample-job-example-url",
                      "job_id": "185394449-1508749660"
                    }
 
JSON success response with HTTP code of 200
                      {
                        "success": true,
                        "message": "The job has been deleted successfully.",
                        "job_url": null,
                        "job_id": null
                      }
 
JSON error response with HTTP code of 203
                        {
                          "success": false,
                          "message": "The company email must be a valid email address.",
                          "job_url": null,
                          "job_id": null
                        }
 
JSON error response with HTTP code of 400
                          {
                            "success": false,
                            "message": "The submitted data is corrupted.",
                            "job_url": null,
                            "job_id": null
                          }
 

  Application  


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.

 

  Application by Email Format  


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.