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 existe actuellement deux possibilités : soit en OAuth2 (recommandé), soit en API key. Cette seconde méthode sera dépréciée en fin 2027.

Authentification en OAuth2

Chaque ATS fournit un identifiant (clientId), un secret (clientSecret) et un endpoint d'authentification chez l'ATS (url). S'ils sont nécessaires, l'ATS peut également donner une liste de credentials à activer. Ce endpoint doit répondre un token JWT que l'équipe ATS Connect transmettra à chaque requête de création de candidature.

La requête au endpoint fournissant le token sera ainsi formé :

curl --location 'https://domaine-ats.com/endpoint-de-recuperation-de-token' \
--header 'Content-Type: application/json' \
--data '{
    "grant_type" : "client_credentials",
    "client_id" : "identifiant-hellowork",
    "client_secret" : "secret-hellowork",
    "scope" : "scope-si-necessaire"
}'

Le header d'envoi de candidature sera ainsi formé :

curl -L -X POST 'https://ats.yourdomain.com/api/applications' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer token' \
--data-raw '{
  ....
  }
}'

Authentification en API (dépréciée en juin 2029)

On peut employer 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": "Dupond",
    "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

Endpoint​

Format de la requête​

Définition des champs​

Structure screenerQuestions (Format normalisé)​

Types supportés​

Exemple détaillé​

Authentification​

Authentification en OAuth2​

Authentification en API (dépréciée en juin 2029)​

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​