Skip to main content

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 :

ChampDéfinition
applicationIdIdentifiant de la candidature côté HelloWork ATS Partner
jobEnsemble de champs concernant l'offre
job.jobIdIdentifiant de l'offre dans l'ATS
job.JobAtsUrlUrl du site carrière de l'offre
applicantListe des champs du candidat
applicant.firstNamePrénom du candidat
applicant.lastNameNom du candidat
applicant.emailEmail du candidat
applicant.phoneNumberNuméro de téléphone du candidat
resume.fileEnsemble de champ concernant le fichier du CV envoyé
resume.file.fileNameNom du fichier du CV envoyé
resume.file.contentTypeLe mimeType du fichier du CV envoyé (eg: application/pdf)
resume.file.dataFichier du CV au format base64
sourceString ou structure de champs représentant la source à l'origine de la candidature
statusApiUrlUrl 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 NameSource à afficher dans l'ATSSource dans le payload
Site Carrière by HelloworkHellowork Career Site (Hellowork)"source": "hellowork-career-site"
BasileBasile (Hellowork)"source": "basile"
SeekubeSeekube (Hellowork)"source": "seekube"
Hellowork.comHellowork.com (Hellowork)"source": "hellowork.com"
JobijobaJobijoba (Hellowork)"source": "jobijoba"
SmartForumSmartForum (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 :

ChampObligatoire / FacultatifDéfinition
atsApplicationIdFacultatifIdentifiant de la candidature au sein de l'ATS si l'information est disponible au moment de la réponse
atsApplicantIdFacultatifIdentifiant 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 :

ChampObligatoire / FacultatifDéfinition
messageObligatoireDescription de l'erreur
codeObligatoireCode permettant de qualifier l'erreur

La définition des code disponible :

valeur de codedescription
AuthenticationProblème d'authentification
ApplicationExistsLa candidature a déjà été envoyée à l'ATS
AttachmentProblème de pièce jointe (CV ou lettre de motivation)
OfferL'offre n'est plus disponible ou est expirée
BodyContenu de la requête mal formatté
FieldSizeProblème de taille de champ
ExternalErreur à été rencontré côté ATS
FieldsValidationErreur 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 codevaleur de codedescription
401 - UnauthorizedAuthenticationProblème d'authentification
400 - BadRequestApplicationExistsLa candidature a déjà été envoyée à l'ATS
400 - BadRequestAttachmentProblème de pièce jointe (CV ou lettre de motivation)
400 - BadRequestOfferL'offre n'est plus disponible ou est expirée
400 - BadRequestBodyContenu de la requête mal formatté
400 - BadRequestFieldSizeProblème de taille de champ
400 - BadRequestExternalErreur à été rencontré côté ATS
500 - InternalServerErrorExternalErreur temporaire à été rencontré côté ATS
400 - BadRequestFieldsValidationErreur de validation de champ requis