Réception des candidatures

La réception de candidatures depuis ATS Connect au format unique HelloWork ATS Partner requiert la mise à disposition, par les ATS, d'un endpoint de réception de ces candidatures.

Vous pouvez retrouver dans cette page toutes les informations utiles à la mise en place de cet endpoint.

Endpoint

Le endpoint à mettre en place dans les ATS pour la réception de candidatures au format HelloWork ATS Partner doit répondre aux critères suivants :

• Verbe : POST
• Url : Libre (Côté ATS Connect le nom de ressource utilisé pour nommer les candidatures est application, suggestion d'url : https://ats.yourdomain.com/api/applications)
• Format des messages : voir paragraphe suivant

Le couple endpoint/apiKey doit être commun à tous les clients. L'Url sera à transmettre aux produits/clients qui souhaitent envoyer des candidatures aux ATS via HelloWork ATS Partner.

Format

Le format des candidatures envoyées aux ATS est le suivant :

{
    "applicationId": "string",
    "job": {
        "jobId": "string",
        "jobAtsUrl": "string"
    },
    "applicant": {
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "phoneNumber": "string"
    },
    "resume": {
        "file": {
            "fileName": "string",
            "contentType": "string",
            "data": "string"   
        }
    },
    "source": "string or object",
    "statusApiUrl": "string"
}

La définition des champs est la suivante :

Champ	Définition
applicationId	Identifiant de la candidature côté HelloWork ATS Partner
job	Ensemble de champs concernant l'offre
job.jobId	Identifiant de l'offre dans l'ATS
job.JobAtsUrl	Url du site carrière de l'offre
applicant	Liste des champs du candidat
applicant.firstName	Prénom du candidat
applicant.lastName	Nom du candidat
applicant.email	Email du candidat
applicant.phoneNumber	Numéro de téléphone du candidat
resume.file	Ensemble de champ concernant le fichier du CV envoyé
resume.file.fileName	Nom du fichier du CV envoyé
resume.file.contentType	Le mimeType du fichier du CV envoyé (eg: application/pdf)
resume.file.data	Fichier du CV au format base64
source	String ou structure de champs représentant la source à l'origine de la candidature
statusApiUrl	Url a appeler pour mettre à jour le statut sur cette candidature, l'id présent dans l'url est l'identifiant de la candidature

Authentification

Pour l'authentification, il a été choisi d'utiliser une API key qui sera transmise en header de chaque requête.

• Cette API key est à fournir à l'équipe ATS Connect HelloWork par l'équipe en charge de l'ATS.
• Le nom du header est au choix des ATS

La gestion de la source

La source est un champ permettant à l'ATS de déterminer la source de la candidature. En fonction du besoin de l'ATS, elle peut être une chaîne de caractères ou un objet plus complexe (voir les 2 exemples ci-dessous avec les 2 types de source) Par défaut, ce sera une chaîne de caractères qui prendra l'une des valeurs du paragraphe 'Gestion des sources de candidatures'.

Exemple de requête envoyée avec source sur un champ

Ci-après un exemple de requête (format cURL) envoyée à l'ATS depuis HelloWork :

curl -L -X POST 'https://ats.yourdomain.com/api/applications' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'YourAuthorizationHeader: token' \
--data-raw '{
  "applicationId": "4b0492a6-d2f6-4baf-9b80-3a0dd0c798c0",
  "job": {
    "jobId": "2022-001-developer",
    "jobAtsUrl": "https://sitecarriere.yourdomain.com/job/2022-001-developer"
  },
  "applicant": {
    "firstName": "Tony",
    "lastName": "Truand",
    "email": "tony-truand@internet.com",
    "phoneNumber": "0601020304",
  },
  "resume": {
    "file": {
      "fileName": "resume.pdf",
      "contentType": "application/pdf",
      "data": "Base64Content"    
    }
  },
  "source": "hellowork.com",
  "statusApiUrl": "https://ats-partner.hellowork.com/v1/applications/4b0492a6-d2f6-4baf-9b80-3a0dd0c798c0/status"
}'

Exemple de requête envoyée avec source sur plusieurs champs

Ci-après un exemple de requête (format cURL) envoyée à l'ATS depuis HelloWork :

curl -L -X POST 'https://ats.yourdomain.com/api/applications' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'YourAuthorizationHeader: token' \
--data-raw '{
  "applicationId": "4b0492a6-d2f6-4baf-9b80-3a0dd0c798c0",
  "job": {
    "jobId": "2022-001-developer",
    "jobAtsUrl": "https://sitecarriere.yourdomain.com/job/2022-001-developer"
  },
  "applicant": {
    "firstName": "Tony",
    "lastName": "Truand",
    "email": "tony-truand@internet.com",
    "phoneNumber": "0601020304",
  },
  "resume": {
    "file": {
      "fileName": "resume.pdf",
      "contentType": "application/pdf",
      "data": "Base64Content"    
    }
  },
  "source": {
      "sourceTypeId": "DIRECT_SOURCING",
      "sourceSubTypeId": "ClientId",
      "sourceId": "CVCatcherWebsite"
  },
  "statusApiUrl": "https://ats-partner.hellowork.com/v1/applications/4b0492a6-d2f6-4baf-9b80-3a0dd0c798c0/status"
}'

Gestion des sources de candidature

Le tableau ci-dessous contient les valeurs par défaut du champ source. Elles correspondent aux différents produits du groupe Hellowork auxquels les clients peuvent souscrire.

Product Name	Source à afficher dans l'ATS	Source dans le payload
Site Carrière by Hellowork	Hellowork Career Site (Hellowork)	"source": "hellowork-career-site"
Basile	Basile (Hellowork)	"source": "basile"
Seekube	Seekube (Hellowork)	"source": "seekube"
Hellowork.com	Hellowork.com (Hellowork)	"source": "hellowork.com"
Smart Diffusion	Smart Diffusion (Hellowork)	"source": "smart-diffusion"
Jobijoba	Jobijoba (Hellowork)	"source": "jobijoba"
SmartForum	SmartForum (Hellowork)	"source": "smartforum"

Réponse

Succès

En cas de succès, il est demandé à l'ATS de renvoyer si possible une réponse au format suivant :

{
    atsApplicationId: string
    atsApplicantId: string
}

La définition des champs est la suivante :

Champ	Obligatoire / Facultatif	Définition
atsApplicationId	Facultatif	Identifiant de la candidature au sein de l'ATS si l'information est disponible au moment de la réponse
atsApplicantId	Facultatif	Identifiant du candidat au sein de l'ATS si l'information est disponible au moment de la réponse

Erreur

En cas d'erreur fonctionnel, il est demandé à l'ATS de renvoyer une réponse au format suivant :

{
    message: string
    code: string
}

La définition des champs est la suivante :

Champ	Obligatoire / Facultatif	Définition
message	Obligatoire	Description de l'erreur
code	Obligatoire	Code permettant de qualifier l'erreur

La définition des code disponible :

valeur de code	description
Authentication	Problème d'authentification
ApplicationExists	La candidature a déjà été envoyée à l'ATS
Attachment	Problème de pièce jointe (CV ou lettre de motivation)
Offer	L'offre n'est plus disponible ou est expirée
Body	Contenu de la requête mal formatté
FieldSize	Problème de taille de champ
External	Erreur à été rencontré côté ATS
FieldsValidation	Erreur de validation de champ requis

Exemple

{
    "message": "L'offre n'a pas été trouvée",
    "code": "Offer"
}

Gestion des status code

Il est conseillé d'associer les status code suivant au code suivant :

status code	valeur de code	description
401 - Unauthorized	Authentication	Problème d'authentification
400 - BadRequest	ApplicationExists	La candidature a déjà été envoyée à l'ATS
400 - BadRequest	Attachment	Problème de pièce jointe (CV ou lettre de motivation)
400 - BadRequest	Offer	L'offre n'est plus disponible ou est expirée
400 - BadRequest	Body	Contenu de la requête mal formatté
400 - BadRequest	FieldSize	Problème de taille de champ
400 - BadRequest	External	Erreur à été rencontré côté ATS
500 - InternalServerError	External	Erreur temporaire à été rencontré côté ATS
400 - BadRequest	FieldsValidation	Erreur de validation de champ requis