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.

  Formats de demande et de réponse  


Vous pouvez utiliser JSON ou XML. En fonction de votre choix de point de terminaison, les données soumises doivent suivre le même format. Il en sera de même pour les données retournées.

Les points de terminaison disponibles sont les suivants :

XML endpoint https://uk.whatjobs.com/api/v1/ats/{ats-name} /xml
JSON endpoint https://uk.whatjobs.com/api/v1/ats/{ats-name} /json
Exemple https://uk.whatjobs.com/api/v1/ats/your-company-name/xml
 

  Authentification par token.  


L'accès à l'API est limité aux personnes possédant un token d'accès. Ce token doit être transmis dans un en-tête HTTP personnalisé X-API-Token.

Pour récupérer votre nom ATS et le Token d'authentification veuillez Nous contacter.

 

  Paramètres de la requête HTTP  


Une demande peut être faite à la version Sandbox de l'API à condition que le paramètre ci-dessous soit fourni dans la requête GET.

Nom Exigé Description
sandbox-mode Non En donnant à ce paramètre booléen la valeur true, l'API fonctionne en mode sandbox, par exemple. sandbox-mode=true

Il n'y a qu'un seul paramètre HTTP POST obligatoire.

Nom Exigé Description
data Oui Le XML ou JSON joint au corps de la requête. Assurez-vous que les données contenues dans le corps du POST correspondent au point de terminaison auquel vous adressez vos requêtes.
Le tableau ci-dessous donne plus de détails sur ce qui est accepté.
 

  Champs de données XML/JSON  


Voici les champs qui peuvent être utilisés dans la demande lorsque la commande est définie sur add.

Nom du champ Exigé Type Informations complémentaires
command Oui Fix Valeur attendue : add
company_email Oui Email Devrait être affiché avec cette étiquette Admin email address dans la page de configuration du tableau des emplois.
company_name Oui String Devrait être affiché avec cette étiquette Company name dans la page de configuration du tableau des emplois.
company_hash Oui String Devrait être affiché avec cette étiquette Hash (Optional) dans la page de configuration du tableau des emplois.
title Oui String Texte libre, le titre de l'annonce. Minimum 3 caractères et limite de 255 caractères.
description Oui String Texte libre, de 100 à 65 000 caractères maximum, description détaillée du poste.
Ce champ peut contenir les balises HTML suivantes : p, br, b, strong, i, u, ul, li, ol
job_type Oui SET Valeurs acceptables : permanent, temporary, contract
job_status Oui SET Valeurs acceptables : full-time, part-time
application_email Oui si l'url est vide Email Requis si application_url est vide
application_url Oui si l'email est vide URL Requis si application_email est vide
industry No SET Valeurs acceptables : Nom de l'industrie, valeurs disponibles dans le Tableau en dessous de.
weeks_to_advertise No SET Valeurs acceptables : 1, 2, 3, 4, 6, 8, 10, 12
salary_type No SET Valeurs acceptables : annum, month, week, day, hour
salary_from No Numeric Un nombre flottant pour le salaire inférieur.
salary_to No Numeric Un nombre flottant pour le salaire supérieur.
salary_currency No SET Valeurs acceptables : gbp, usd, eur
salary_benefits No String Texte libre, informations supplémentaires sur le salaire.
location No String Texte libre, format suggéré : country, region, county, town
postcode No String Code postal valide.
reference No String Texte libre, la référence du poste attribuée à l'annonce par le recruteur.
 

Le tableau ci-dessous décrit les champs qui peuvent être utilisés dans la requête lorsque la commande est définie sur supprimer.

Nom du champ Exigé Type Informations complémentaires
command Oui Fix Valeur attendue : delete
company_email Oui Email Devrait être affiché avec cette étiquette Admin email address dans la page de configuration du tableau des emplois.
company_name Oui String Devrait être affiché avec cette étiquette Company name dans la page de configuration du tableau des emplois.
company_hash Oui String Devrait être affiché avec cette étiquette Hash (Optional) dans la page de configuration du tableau des emplois.
job_id Oui String Il s'agit de la même valeur que celle qui sera renvoyée dans la réponse de l'application add avec le format suivant : integer-integer
 

  Valeurs acceptées par industrie  


Le tableau ci-dessous contient toutes les valeurs valables pour le champ "industrie".

Industries
  • Comptabilité
  • Administration et secrétariat
  • Aérospatiale et aviation
  • Agriculture Pêche, forêts et conservation
  • Automobile
  • Services bancaires et financiers
  • Restauration et hôtellerie
  • Charité et bénévolat
  • Construction et immobilier
  • Service à la clientèle
  • Défense et affaires militaires
  • Conduite et transport
  • Éducation et formation
  • Électronique
  • Énergie, services publics, pétrole et gaz
  • Ingénierie
  • Mode et arts
  • FMCG
  • Diplômés et stagiaires
  • Santé, sécurité et sûreté
  • Soins de santé et médecine
  • Ressources humaines et personnel
  • Technologies de l'information
  • Assurance
  • Journalisme, édition et traduction
  • Mentions légales
  • Loisirs, tourisme et divertissement
  • Logistique et entrepôt
  • Gestion et conseil
  • Fabrication et production
  • Marketing, publicité et relations publiques
  • Médias, design et création
  • Assistant personnel
  • Pharmaceutique
  • Secteur public et gouvernement
  • Achats et approvisionnement
  • Recrutement
  • Commerce de détail et de gros
  • Ventes
  • Scientifique
  • Soins sociaux
  • Télécommunications
 

  Exemple de requête XML valide  


 
Exemple XML pour la commande d'ajout
          <?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>
 
Exemple XML cURL pour la commande d'ajout
            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'
          
 
Exemple XML pour la commande Supprimer
            <?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>
          
 
Exemple XML cURL pour la commande Supprimer
            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'
          
 
Exemple JSON pour la commande "Ajouter".
            {
              "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"
            }
 
Echantillon JSON cURL pour la commande "Ajouter".
              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'
            
 
Exemple JSON pour la commande Supprimer
              {
                "command": "delete",
                "company_email": "[email protected]",
                "company_name": "Sample Company Name",
                "company_hash": "",
                "job_id": "185394403-1508429206"
              }
 
Echantillon JSON cURL pour la commande Supprimer
                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'
              
 

  Codes d'état de la réponse HTTP  


Depending on action’s result the returned HTTP status code can be one of the values below.

Code de statut Raison Destinataire du message retourné Description
200 Succès Utilisateur final C'est le résultat d'une action réussie et la valeur de la variable de message retournée doit être affichée à l'utilisateur final.
203 Erreur dans les données de l'utilisateur Utilisateur final Cela se produit chaque fois que l'utilisateur final saisit des informations non valides. Le message renvoyé doit être affiché à l'utilisateur. Par exemple, lorsqu'un utilisateur saisit une adresse électronique non valide ou ne dispose pas d'un crédit suffisant.
400 Bug dans la configuration de l'ATS ATS Cela signifie qu'il y avait un problème dans la structure des données soumises. Cela se produit lorsqu'il y a un bug dans la configuration de l'ATS. Par exemple, la valeur du paramètre de commande est autre que add ou delete, ou la valeur du weeks_to_advertise est hors limites. La raison peut être trouvée dans la variable de message retournée.
503 Erreur API ATS L'API est temporairement indisponible et ne pourra pas traiter la demande pendant un certain temps. Le message renvoyé fournit plus d'informations. Dans ce cas, le résultat renvoyé peut être un HTML.
 

  Format de réponse  


La réponse renvoyée sera XML ou JSON, selon le point de terminaison sélectionné. Toutes les réponses contiendront les variables ci-dessous.

Nom Description
succès Une valeur booléenne indique le statut de la réponse renvoyée, qui peut être True (avec le code HTTP 200) ou False (avec le code HTTP 203, 400 ou 503).
message Le message retourné doit être affiché à l'utilisateur final lorsque le code HTTP est soit 200 soit 203.
job_url Il contient l'URL du job en cas de succès add exécution de la commande et null sinon.
job_id Contient l'identifiant du job en cas de succès add exécution de la commande et null sinon. Cet identifiant doit être fourni lors de la commande de suppression.
 

  Exemples de réponses  


 
Réponse XML positive avec un code HTTP de 200
                <?xml version="1.0" encoding="UTF-8" ?>
                <response>
                <success><![CDATA[true]]></success>
                <message><![CDATA[L'emploi a été ajouté avec succès.]]></message>
                <job_url><![CDATA[https://uk.whatjobs.com/job/sample-job-example-url]]></job_url>
                <job_id><![CDATA[185394449-1508749660]]></job_id>
                </response>
              
 
Réponse XML positive avec un code HTTP de 200
                <?xml version="1.0" encoding="UTF-8" ?>
                <response>
                <success><![CDATA[true]]></success>
                <message><![CDATA[Le travail a été supprimé avec succès.]]></message>
                <job_url><![CDATA[]]></job_url>
                <job_id><![CDATA[]]></job_id>
                </response>
 
Réponse d'erreur XML avec un code HTTP de 203
                  <?xml version="1.0" encoding="UTF-8" ?>
                  <response>
                  <success><![CDATA[false]]></success>
                  <message><![CDATA[L'adresse électronique de l'entreprise doit être une adresse électronique valide.]]></message>
                  <job_url><![CDATA[]]></job_url>
                  <job_id><![CDATA[]]></job_id>
                  </response>
                
 
Réponse d'erreur XML avec un code HTTP de 400
                  <?xml version="1.0" encoding="UTF-8" ?>
                  <response>
                  <success><![CDATA[false]]></success>
                  <message><![CDATA[Les données soumises sont corrompues.]]></message>
                  <job_url><![CDATA[]]></job_url>
                  <job_id><![CDATA[]]></job_id>
                  </response>
 
Réponse de succès JSON avec un code HTTP de 200
                    {
                      "success": true,
                      "message": "L'emploi a été ajouté avec succès.",
                      "job_url": "https://uk.whatjobs.com/job/sample-job-example-url",
                      "job_id": "185394449-1508749660"
                    }
 
Réponse de succès JSON avec un code HTTP de 200
                      {
                        "success": true,
                        "message": "L'emploi a été supprimé avec succès.",
                        "job_url": null,
                        "job_id": null
                      }
 
Réponse d'erreur JSON avec un code HTTP de 203
                        {
                          "success": false,
                          "message": "L'adresse électronique de l'entreprise doit être une adresse électronique valide.",
                          "job_url": null,
                          "job_id": null
                        }
 
JSON error response with HTTP code of 400
                          {
                            "success": false,
                            "message": "Les données soumises sont corrompues.",
                            "job_url": null,
                            "job_id": null
                          }
 

  Application  


En fonction de la méthode de candidature, lorsqu'un utilisateur postule pour un emploi, nous utiliserons soit application_email ou application_url pour envoyer les détails du candidat à l'ATS par courriel ; ou rediriger l'utilisateur vers l'URL fournie. Si les deux valeurs de variables sont disponibles, la méthode utilisée par défaut sera celle de la demande par email.

 

  Format de la demande par e-mail  


Le courrier de candidature sera envoyé à partir d'une adresse électronique générée de manière unique à l'adresse électronique de candidature donnée, avec l'objet suivant Application for {job-title} - {job-reference}.

L'e-mail contient également reply-to avec l'adresse électronique de l'utilisateur final.

Le corps de l'e-mail contient une version HTML et une version en texte brut. Les deux versions contiennent les champs expliqués ci-dessous. Les balises HTML formatent la version HTML, et la version texte est au format JSON.

Nom du champ Description
job_title Titre du poste
job_reference Références professionnelles, si elles sont fournies.
first_name Prénom du demandeur d'emploi
last_name Nom de famille du demandeur d'emploi
email_address Adresse électronique du demandeur d'emploi
covering_letter La lettre de motivation, si elle est fournie.