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 des candidatures.

Endpoint

Le endpoint de réception doit respecter les critères suivants :

Méthode : POST
URL : libre (exemple recommandé : https://ats.yourdomain.com/api/applications)
Format : application/json

💡 Le couple endpoint / apiKey est commun à tous les clients et doit être communiqué au groupe HelloWork.

Format de la requête

Le corps de la requête JSON est structuré comme suit :

{
  "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",
  "screenerQuestions": [
    {
      "id": "string",
      "question": "string",
      "type": "text | textarea | number | select | multiselect | boolean | date",
      "answer": "string | string(date format YYYY-MM-DD) | number | boolean | string[]",
      "options": [
        { "value": "string", "label": "string" }
      ]
    }
  ]
}

Définition des champs

Champ	Type	Description
`applicationId`	string	Identifiant unique de la candidature côté HelloWork ATS Partner.
`job`	objet	Informations relatives à l’offre concernée.
`job.jobId`	string	Identifiant unique de l’offre dans l’ATS.
`job.jobAtsUrl`	string	URL de l’offre sur le site carrière.
`applicant`	objet	Informations sur le candidat.
`applicant.firstName`	string	Prénom du candidat.
`applicant.lastName`	string	Nom du candidat.
`applicant.email`	string	Adresse e-mail du candidat.
`applicant.phoneNumber`	string	Numéro de téléphone du candidat.
`resume.file`	objet	Fichier CV transmis au format Base64 avec ses métadonnées.
`source`	string / objet	Provenance de la candidature.
`statusApiUrl`	string	URL d’API permettant à l’ATS de notifier HelloWork des changements de statut.
`screenerQuestions`	array	Liste des questions de présélection.

Structure `screenerQuestions` (Format normalisé)

La clé screenerQuestions contient un tableau de questions structurées selon un format standardisé.

Chaque question possède :

id : identifiant unique
question : libellé affiché
type : type normalisé (voir tableau ci-dessous)
answer : réponse du candidat

Types supportés

Type	Description	Format `answer`
`text`	Texte court	`string`
`textarea`	Texte long	`string`
`number`	Valeur numérique	`number`
`select`	Choix unique	`string` = id d’une option
`multiselect`	Choix multiples	`string[]` = liste d’ids
`boolean`	Oui / Non	`true` / `false`
`date`	Date ISO 8601	`string` = `YYYY-MM-DD`

Exemple détaillé

"screenerQuestions": [
  {
    "id": "availability_weeks",
    "question": "Dans combien de semaines êtes-vous disponible ?",
    "type": "number",
    "answer": 5
  },
  {
    "id": "languages",
    "question": "Quelles langues parlez-vous ?",
    "type": "multiselect",
    "options": [
      { "value": "fr", "label": "Français" },
      { "value": "en", "label": "Anglais" },
      { "value": "es", "label": "Espagnol" }
    ],
    "answer": ["fr", "en"]
  },
  {
    "id": "remote_ok",
    "question": "Acceptez-vous le télétravail ?",
    "type": "boolean",
    "answer": true
  },
  {
    "id": "why_us",
    "question": "Pourquoi souhaitez-vous rejoindre notre entreprise ?",
    "type": "textarea",
    "answer": "Je partage vos valeurs et votre approche de l'innovation."
  },
  {
    "id": "start_date",
    "question": "À quelle date pouvez-vous commencer ?",
    "type": "date",
    "answer": "2025-03-15"
  },
  {
    "id": "work_mode",
    "question": "Quel mode de travail préférez-vous ?",
    "type": "select",
    "options": [
      { "value": "onsite", "label": "Présentiel" },
      { "value": "remote", "label": "Télétravail" },
      { "value": "hybrid", "label": "Hybride" }
    ],
    "answer": "hybrid"
  }
]

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 contenant source complexe

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": "Michel",
    "lastName": "Ducpond",
    "email": "michel-dupond@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"
Jobijoba	`Jobijoba (Hellowork)`	"source": "jobijoba"
SmartForum	`SmartForum (Hellowork)`	"source": "smartforum"
Stori	`Stori by Hellowork (Hellowork)`	"source": "stori-by-hellowork"
Site Carrière Interne by Hellowork	`Hellowork Career Site Internal (Hellowork)`	"source": "hellowork-career-site-internal"

Réponse attendue

✅ En cas de succès

{
  "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

❌ En cas d’erreur fonctionnelle

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

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
`RejectedCandidate`	Le candidat est rejeté par 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
`OfferFormat`	Le format de l'id de l'offre n'est pas celui attendu
`OfferExpiredOrUnpublished`	L'offre à expirée, à été supprimée ou est dépubliée
`FieldSize`	Problème de taille de champ
`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	`RejectedCandidate`	Le candidat est rejeté par l'ATS - Présicez pourquoi dans le message
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	`OfferFormat`	Le format de l'id de l'offre n'est pas celui attendu - Présicez le format attendu dans le message
400 - BadRequest	`FieldSize`	Problème de taille de champ
400 - BadRequest	`FieldsValidation`	Erreur de validation de champ requis

Réception des candidatures

Endpoint​

Format de la requête​

Définition des champs​

Structure screenerQuestions (Format normalisé)​

Types supportés​

Exemple détaillé​

Authentification​

La gestion de la source​

Exemple de requête contenant source complexe​

Gestion des sources de candidature​

Réponse attendue​

✅ En cas de succès​

❌ En cas d’erreur fonctionnelle​

Gestion des status code​