Heyalink Développeurs API Emploi
API Emploi
Vos offres d’emploi, publiées et tenues à jour depuis votre site ou votre logiciel de recrutement.
Démarrage rapide
-
Créez une clé
Sur l’écran API Emploi de votre page pro, une clé d’essai vérifie tout et ne publie rien.
Se connecter pour créer une clé -
Vérifiez qu’elle répond
Un appel à /moi rend votre page pro et les droits de la clé.
GET /moi -
Publiez une offre
Envoyez-la d’abord à blanc, avec le paramètre dry_run : Heyalink répond sans rien écrire.
Voir l’exemple
Connectez-vous avec un compte qui gère une page pro pour essayer les exemples ici même, dans le bac à sable.
En bref
L'API Emploi de Heyalink publie les offres d'emploi de votre page entreprise depuis votre site ou votre logiciel de recrutement. Vous gardez la main chez vous : une offre créée, modifiée ou retirée chez vous l'est aussi sur Heyalink.
Elle est comprise dans la formule Grands comptes de votre page. Elle a sa sœur, l'API Formation, pour les formations : ce sont deux API distinctes, avec chacune ses clés. Une clé de l'API Emploi ne fait rien sur les formations.
Pendant le lancement : les abonnements ouvriront avec les paiements, à venir. D'ici là, pour essayer l'API ou publier pour de bon, écrivez-nous à info-contact@heyalink.com : nous ouvrons l'accès page par page.
Trois façons de vous brancher, à combiner si besoin :
- votre page carrières, sans aucun développement : collez son adresse, Heyalink y trouve vos
offres seul (balisage schema.org
JobPosting, celui que Google lit) et les tient à jour ; - votre logiciel de recrutement, sans aucun développement : collez l'adresse de votre page hébergée par Greenhouse, Lever, Recruitee, SmartRecruiters ou Ashby ; ou donnez l'adresse d'un flux d'offres (XML des jobboards, RSS, JSON) ;
- l'API : votre logiciel envoie chaque offre à Heyalink, en JSON ; ou votre agent d'IA, par le serveur MCP.
Vos offres restent toujours à jour sans geste de votre part : une offre ajoutée, modifiée, retirée, pourvue ou expirée chez vous l'est aussi sur Heyalink. Une offre publiée ainsi est une offre de votre page comme les autres : sur le site, dans les applications, dans les alertes emploi, avec les candidatures.
Se brancher en cinq minutes
- Sur Heyalink, ouvrez la rubrique Emploi, onglet Mes offres, puis Connecter mes offres automatiquement (ou depuis la page de l’entreprise, onglet Services). L'écran API Emploi s'ouvre ; choisissez la page si vous en gérez plusieurs.
- Créez une clé : donnez-lui un nom (« Site carrière », « Logiciel RH »), cochez ce qu'elle peut faire (lire les offres, les publier), acceptez les conditions. La clé ne s'affiche qu'une fois : copiez-la dans le coffre de votre logiciel. Pour vos essais, cochez « Clé d'essai » : elle vérifie tout et ne publie rien.
- Vérifiez qu'elle marche :
- Prouvez que vous possédez le domaine de votre site (voir « Prouver votre domaine ») : sans lui, seule la clé d'essai publie. Puis publiez votre première offre (exemples plus bas).
- Suivez le résultat dans le journal de l'écran API Emploi, ou par
GET /journal.
curl https://heyalink.com/api/emploi/v1/moi -H "Authorization: Bearer hl_emploi_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/emploi/v1/moi", {
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/moi');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get(
"https://heyalink.com/api/emploi/v1/moi",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
La clé
- Elle commence par
hl_emploi_live_et compte 63 caractères. Ce préfixe lisible permet aux outils de détection de secrets (GitHub, GitGuardian) de la repérer si elle est oubliée dans un dépôt. - Elle va dans l'en-tête de chaque appel :
Authorization: Bearer hl_emploi_live_VOTRECLE. Jamais dans une adresse, un dépôt de code ou une page web publique. - Elle appartient à une page et à cette API seule : elle ne lit ni ne touche les offres d'une autre page, et une clé de l'API Formation reçoit 403 ici (comme celle-ci sur l'API Formation).
- Elle ne marche que tant que la page a la formule Grands comptes : sans elle, chaque appel répond 403.
- Elle ne fait que ce que ses droits permettent :
offres:lecture,offres:ecriture(publier permet aussi de lire). - Facultatif, à sa création : une durée de vie (30 jours, 90 jours, 1 an) et une liste
d'adresses IP autorisées (par exemple
203.0.113.0/24) ; un appel venu d'ailleurs répond 403. - Une page peut avoir jusqu'à dix clés actives sur l'API Emploi : une par logiciel, pour pouvoir en couper une sans toucher les autres. Révoquer une clé la coupe aussitôt.
- Remplacer une clé (rotation) en crée une nouvelle aux mêmes réglages, durée de vie comprise ; l'ancienne marche encore 7 jours, le temps de la changer dans votre logiciel, sans coupure. Si la clé a fuité, choisissez le remplacement d'urgence : l'ancienne est coupée tout de suite, avec ses jetons OAuth.
- Une clé d'essai (
hl_emploi_test_) a sa propre limite d'appels, plus basse que celle d'une vraie clé (GET /moila donne).
Le bac à sable
Une clé d'essai commence par hl_emploi_test_. Elle donne exactement les mêmes réponses,
validations et erreurs qu'une vraie clé, mais ses offres vivent à part : elles ne sont jamais
publiées ni vues des membres. Vous pouvez les créer, les lister, les modifier, les archiver et les
supprimer comme de vraies offres ; elles sont effacées 7 jours après leur dernière modification.
Chaque réponse porte "bac_a_sable": true et l'en-tête Heyalink-Bac-A-Sable: oui. Vos
webhooks de test sont prévenus aussi, avec "bac_a_sable": true dans donnees. Branchez votre
logiciel avec elle, puis passez à une clé hl_emploi_live_.
Le journal de test (GET /journal avec la clé d'essai, ou l'écran API Emploi) garde chaque
appel avec sa requête et sa réponse complètes, secrets masqués.
La validation à blanc
Avec une vraie clé, ajoutez ?dry_run=1 à n'importe quelle écriture (ou l'en-tête
Heyalink-Simulation: 1) : tout est vérifié (clé, droits, champs, référence) et la réponse est
celle d'une vraie écriture, avec "simulation": true. Rien n'est écrit.
Essayer sans rien installer
- « Essayer » dans cette documentation, connecté à Heyalink : chaque exemple part avec un jeton du bac à sable de votre page.
- Données d'exemple valides telles quelles : offres.json.
- Collections prêtes à importer, tirées de la spécification OpenAPI de l'API Emploi :
Postman,
Bruno. Mettez votre clé d'essai
dans la variable
cle. - Tester ma source (écran API Emploi) : ce que Heyalink importerait de votre page carrières, de votre logiciel ou de votre flux, champ par champ, avec les erreurs, sans rien publier.
OAuth 2.0
Si votre logiciel préfère OAuth, échangez la clé contre un jeton d'une heure (octroi
« client credentials », RFC 6749) : client_id est l'identifiant client de la clé (hlc_…,
affiché sur l'écran API Emploi), client_secret la clé elle-même. scope restreint les droits
du jeton (facultatif), pris parmi offres:lecture et offres:ecriture.
Le jeton s'emploie ensuite comme une clé : Authorization: Bearer hl_at_…. Il ne vaut que pour
l'API Emploi, et tombe avec la clé (révocation, expiration).
Les anciennes clés
- Les clés de l'ancienne API Recruteur Premium (
hlk_…, adresse/api/recruteur/v1) marchent toujours, jusqu'à leur remplacement depuis l'écran API Emploi : « Remplacer » donne une cléhl_emploi_live_; l'ancienne marche encore 7 jours (ou s'arrête tout de suite en urgence). - Les clés créées avant le 21 octobre 2026 (
hle_…,hl_live_…,hl_test_…) marchent aussi jusqu'à leur remplacement. Leur API se déduit de leurs droits : avecoffres:…, elles ouvrent l'API Emploi. Leur remplacement donne une clé de l'API Emploi seule. - L'ancienne adresse commune
/api/entreprises/v1reste servie pour elles ; le cloisonnement des deux API y vaut aussi. Passez àhttps://heyalink.com/api/emploi/v1à votre rythme.
curl -X PUT "https://heyalink.com/api/emploi/v1/offres/CC-2026-014?dry_run=1" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{
"titre": "Chef de chantier gros œuvre",
"description": "<p>Deux équipes.</p>",
"lieu": "Toulouse"
}'
const reponse = await fetch("https://heyalink.com/api/emploi/v1/offres/CC-2026-014?dry_run=1", {
method: "PUT",
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"titre": "Chef de chantier gros œuvre",
"description": "<p>Deux équipes.</p>",
"lieu": "Toulouse"
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/offres/CC-2026-014?dry_run=1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"titre": "Chef de chantier gros œuvre",
"description": "<p>Deux équipes.</p>",
"lieu": "Toulouse"
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.put(
"https://heyalink.com/api/emploi/v1/offres/CC-2026-014?dry_run=1",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"titre": "Chef de chantier gros œuvre",
"description": "<p>Deux équipes.</p>",
"lieu": "Toulouse",
},
)
print(reponse.status_code, reponse.text)
curl -X POST "https://heyalink.com/api/emploi/v1/oauth/token" \
-u "hlc_VOTREIDENTIFIANT:hl_emploi_live_VOTRECLE" \
-d grant_type=client_credentials \
-d scope="offres:ecriture"
const reponse = await fetch("https://heyalink.com/api/emploi/v1/oauth/token", {
method: "POST",
headers: {
"Authorization": "Basic " + btoa("hlc_VOTREIDENTIFIANT:hl_emploi_live_VOTRECLE"),
},
body: new URLSearchParams({
"grant_type": "client_credentials",
"scope": "offres:ecriture"
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/oauth/token');
curl_setopt_array($ch, [
CURLOPT_USERPWD => 'hlc_VOTREIDENTIFIANT:hl_emploi_live_VOTRECLE',
CURLOPT_POSTFIELDS => http_build_query([
'grant_type' => 'client_credentials',
'scope' => 'offres:ecriture',
]),
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/emploi/v1/oauth/token",
auth=("hlc_VOTREIDENTIFIANT", "hl_emploi_live_VOTRECLE"),
data={
"grant_type": "client_credentials",
"scope": "offres:ecriture",
},
)
print(reponse.status_code, reponse.text)
{
"access_token": "hl_at_…",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "offres:ecriture"
}
Prouver votre domaine
Une publication pour de bon (et sa validation à blanc) demande que votre page ait prouvé qu'elle possède le domaine de son site. Un SIRET vérifié dit que l'entreprise existe, pas que c'est bien elle qui publie : la preuve de domaine protège vos candidats contre une page qui usurperait votre nom. Le bac à sable, lui, reste ouvert sans preuve. Les domaines prouvés sont ceux de la page : ils valent pour l'API Emploi comme pour l'API Formation.
- Déclarez le domaine :
POST /domainesavec{"domaine": "votre-site.fr"}, ou sur l'écran API Emploi. La réponse donne un jeton propre au domaine. - Posez-le sur votre site, au choix : la balise
<meta name="heyalink-verification" content="JETON">dans la page d'accueil, ou un fichierhttps://votre-site.fr/.well-known/heyalink.txtqui contient le jeton. - Vérifiez :
POST /domaines/votre-site.fr/verification.domaine.prouvepasse àtrue.
Le domaine prouvé vaut aussi pour ses sous-domaines (carrieres.votre-site.fr). Le lien de
candidature de vos offres (lien_candidature) doit mener à un domaine prouvé de votre page :
sinon l'offre est refusée en 422, sur le champ. Une page carrières ou un flux déjà prouvés comme
source valent preuve de leur domaine. La preuve est revue chaque semaine : retirée de votre site,
elle ne compte plus. Il n'y a pas d'autre voie : pas de validation à la main. GET /domaines
liste vos domaines, DELETE /domaines/votre-site.fr en retire un.
Adresse et format
| Adresse de base | https://heyalink.com/api/emploi/v1 |
| Format | JSON en UTF-8 (Content-Type: application/json), réponses en JSON |
| Description complète | OpenAPI 3.1 : https://heyalink.com/api/emploi/v1/openapi.json, à importer dans Postman, Insomnia ou un générateur de client |
| Limite | 300 appels par minute et par clé, annoncés sur chaque réponse |
Limite d'appels. Chaque réponse porte les en-têtes RateLimit-Policy et RateLimit
(appels restants, secondes avant la remise à zéro). Au-delà, la réponse est 429 avec
Retry-After : attendez ce nombre de secondes, ou regroupez vos offres avec /lot.
Rejouer sans risque. Ajoutez Idempotency-Key: <un identifiant unique> à une écriture :
rejouée avec la même valeur dans les 24 heures (après une coupure réseau, par exemple), elle rend
la même réponse sans rien refaire, avec Idempotent-Replayed: true. La même valeur pour une autre
requête répond 422.
Lire sans retélécharger. Chaque lecture porte un ETag ; renvoyez-le en If-None-Match :
si rien n'a changé, la réponse est 304, sans corps.
Langue. Les messages sont en français ; envoyez Accept-Language: en pour les avoir en
anglais.
État de l'API. GET https://heyalink.com/api/emploi/v1/sante, public et sans clé, donne l'état et la version :
Chaque offre est désignée par votre référence (le numéro de l'offre chez vous) : lettres,
chiffres, -, _, . et :, 191 caractères au plus. C'est elle qui rend les appels sûrs à
rejouer : envoyer deux fois la même référence modifie l'offre, ne la double jamais.
curl https://heyalink.com/api/emploi/v1/sante
const reponse = await fetch("https://heyalink.com/api/emploi/v1/sante");
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/sante');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get("https://heyalink.com/api/emploi/v1/sante")
print(reponse.status_code, reponse.text)
Les offres d'emploi
| Appel | Effet |
|---|---|
PUT /offres/{reference} |
crée l'offre (201) ou la modifie (200) |
GET /offres/{reference} |
l'offre et son état |
GET /offres?limite=100&curseur=… |
vos offres, de la plus récente à la plus ancienne, 100 au plus par page ; suivant donne le curseur de la page d'après (vide à la dernière) |
POST /offres/{reference}/pourvue |
le poste est pourvu : l'offre sort du site, archivée « pourvue » |
POST /offres/{reference}/fermer |
c'est fini (poste pourvu) : l'offre sort du site et de votre limite, les candidats sont prévenus ; état fermee (depuis la v1.11.0) |
POST /offres/{reference}/rouvrir |
une offre fermée revient en ligne, dans la limite de votre formule (403 sinon) |
GET /offres/{reference}/apercu |
la fiche telle qu'un membre la voit sur Heyalink (fiche), son état et le nombre de candidats (reponses) |
POST /offres/{reference}/pieces |
joindre des photos (photos, 6 au plus, JPEG, PNG, WebP ou HEIC, 10 Mo chacune ; la première est le visuel de l'annonce et de son partage) et des PDF (documents, 6 au plus, 20 Mo chacun), chacun {nom, donnees} en base64 (depuis la v1.12.0) |
PUT /offres/{reference}/pieces/ordre |
ranger les photos : ordre, les identifiants dans l'ordre voulu |
DELETE /offres/{reference}/pieces/{piece} |
retirer une photo ou un PDF (le fichier est effacé) |
POST /offres/{reference}/archivage |
l'offre sort du site, archivée ; un PUT la ramène |
DELETE /offres/{reference} |
la supprime (204, même si elle n'existait pas) ; un PUT la ramène avec ses candidatures |
POST /offres/lot |
jusqu'à 100 offres et 100 retraits en un appel |
POST /offres/synchronisation |
la liste complète de vos références en ligne : tout ce qui manque est archivé |
| Champ | Obligatoire | Contenu |
|---|---|---|
titre |
oui | l'intitulé du poste, 200 caractères au plus |
description |
oui | le texte de l'offre, 20 000 caractères au plus ; le HTML est accepté et gardé en texte |
lieu |
oui | la ville, par exemple Toulouse (31) ; vide, la ville de votre page |
code_postal |
non | 5 chiffres ; il range l'offre dans son département |
metier |
non | le métier, par exemple Chef de chantier ; reconnu, il fait proposer l'offre aux bons membres par l'algorithme de Heyalink |
type_contrat |
non | CDI, CDD, Intérim, Apprentissage, Alternance, Stage, Saisonnier (les mots anglais des jobboards sont compris : permanent, temporary, internship…) |
salaire |
non | en clair, 50 caractères au plus |
secteur |
non | le secteur d'activité, 120 caractères au plus |
lien_candidature |
non | l'adresse https:// où postuler chez vous ; absente, on postule sur Heyalink |
date_expiration |
non | ignoré depuis le 07/11/2026 (v1.10.0) : accepté, sans effet, toujours null dans les réponses. Une offre n'a plus de date de fin : elle reste en ligne jusqu'à ce que vous l'archiviez |
metier_code |
non | le code d'un métier du référentiel de Heyalink (chef-de-chantier-batiment) ; inconnu, l'offre est refusée (422) |
famille_code |
non | le code d'une des 39 familles de métiers (entreprise-generale) ; sans lui, la famille du métier |
code_rome |
non | le code ROME de France Travail, une lettre et quatre chiffres (F1202) |
experience_mois |
non | l'expérience demandée, en mois, de 0 (débutant accepté) à 600 |
temps_de_travail |
non | plein ou partiel ; un type_contrat FULL_TIME ou PART_TIME le donne aussi |
teletravail |
non | non, partiel (hybride) ou total |
alternance |
non | apprentissage ou professionnalisation |
salaire_min, salaire_max |
non | le salaire brut en nombres, en euros ; salaire_max au moins égal à salaire_min |
salaire_periode |
avec un salaire en nombres | heure, jour, semaine, mois ou an |
Les champs à partir de metier_code (v1.6.0) sont facultatifs et suivent des listes fermées : une
valeur hors liste est refusée en 422, avec un exemple valide. Ils servent les filtres d'Emploi :
une offre sans la donnée sort du filtre correspondant, elle n'en reçoit jamais une fausse.
La réponse dit aussi ce qui s'est passé, dans resultat : creee, modifiee, restauree
(revenue en ligne), inchangee (rien n'a changé, rien n'est réécrit) ou doublon (le même
contenu est déjà en ligne sous une autre référence : rien n'est créé).
Une offre peut attendre avant de paraître (Grands comptes). Quand le plafond de facture du
mois est atteint, ou qu'une facture reste impayée quatorze jours après son échéance, l'offre est
bien enregistrée mais reste hors ligne : etat vaut en_attente et attente dit pourquoi
(motif : plafond ou impaye), depuis quand, et parait_au_plus_tard_le (au plafond, le
premier jour du mois suivant ; plus tôt si vous relevez votre plafond ; sur un impayé, au
paiement). Elle se relit par sa référence. Le webhook annonce.en_attente vous prévient, puis
annonce.publiee quand elle paraît. Pour toute autre offre, attente vaut null.
Les avertissements ne bloquent jamais : ils disent ce qui manque pour bien ranger l'offre (un métier que Heyalink ne reconnaît pas, avec les plus proches ; un lieu sans département). Corrigez-les quand vous pouvez : l'offre sera mieux proposée.
Les signalements (signalements, depuis la v1.6.0) ne bloquent jamais non plus. Chacun a un
code, un champ et un message :
code |
Sens |
|---|---|
champ_ignore |
vous avez envoyé un champ que l'API ne connaît pas : il n'est ni publié ni refusé (vingt au plus sont nommés) |
champ_recommande_absent |
un champ manque, et l'offre sortira du filtre qu'il remplit (expérience, salaire, contrat…) |
valeur_deduite |
vous n'avez pas envoyé ce champ : l'algorithme de Heyalink l'a déduit, origine dit d'où (code_rome, metier, titre, metier_code, code_naf, type_contrat) |
incoherence |
deux champs qui ne vont pas ensemble |
Une valeur déduite n'est jamais présentée comme la vôtre : l'offre la liste dans champs_deduits.
Envoyez le champ pour en décider vous-même. Le grand secteur (secteur) se lit depuis la famille,
au moment de la réponse.
Relire une offre, et la liste de vos offres :
Le poste est pourvu : l'offre sort du site, archivée « pourvue ».
Une offre retirée par la modération de Heyalink ne revient jamais, ni par l'API (422 sur
reference), ni par une source : écrivez à l'équipe si vous pensez à une erreur.
Supprimée ou fermée sur Heyalink (depuis la v1.11.0)
Un gérant de votre page peut fermer ou supprimer l'offre sur Heyalink.
- Supprimée : elle ne revient jamais. Renvoyer la même référence (
PUT, envoi par lot) répond409,codeannonce_supprimee, avec la date (supprimee_le) et ce texte : « Cette annonce a été supprimée sur heyalink le … par un gérant de la page. Pour la republier, utilisez une nouvelle référence. » Un flux (page carrières, logiciel) la saute et le note dans son bilan (supprimees_sur_le_site) et dans le journal. - Fermée : renvoyée, elle se met à jour mais reste fermée (état
fermee) ; seul un gérant la rouvre, ou vous parPOST /offres/{reference}/rouvrir.
curl -X PUT "https://heyalink.com/api/emploi/v1/offres/CC-2026-014" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{
"titre": "Chef de chantier gros œuvre",
"description": "<p>Vous dirigez deux équipes sur des chantiers de logements.</p>",
"lieu": "Toulouse",
"code_postal": "31000",
"metier": "Chef de chantier",
"type_contrat": "CDI",
"salaire": "38 000 € par an"
}'
const reponse = await fetch("https://heyalink.com/api/emploi/v1/offres/CC-2026-014", {
method: "PUT",
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"titre": "Chef de chantier gros œuvre",
"description": "<p>Vous dirigez deux équipes sur des chantiers de logements.</p>",
"lieu": "Toulouse",
"code_postal": "31000",
"metier": "Chef de chantier",
"type_contrat": "CDI",
"salaire": "38 000 € par an"
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/offres/CC-2026-014');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"titre": "Chef de chantier gros œuvre",
"description": "<p>Vous dirigez deux équipes sur des chantiers de logements.</p>",
"lieu": "Toulouse",
"code_postal": "31000",
"metier": "Chef de chantier",
"type_contrat": "CDI",
"salaire": "38 000 € par an"
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.put(
"https://heyalink.com/api/emploi/v1/offres/CC-2026-014",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"titre": "Chef de chantier gros œuvre",
"description": "<p>Vous dirigez deux équipes sur des chantiers de logements.</p>",
"lieu": "Toulouse",
"code_postal": "31000",
"metier": "Chef de chantier",
"type_contrat": "CDI",
"salaire": "38 000 € par an",
},
)
print(reponse.status_code, reponse.text)
{
"offre": {
"reference": "CC-2026-014",
"titre": "Chef de chantier gros œuvre",
"departement": "31",
"metier": "Chef de chantier",
"etat": "en_ligne",
"adresse": "https://heyalink.com/emplois/chef-de-chantier-gros-oeuvre-12",
"source": "api"
},
"avertissements": [],
"success": true
}
curl "https://heyalink.com/api/emploi/v1/offres/CC-2026-014" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/emploi/v1/offres/CC-2026-014", {
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/offres/CC-2026-014');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get(
"https://heyalink.com/api/emploi/v1/offres/CC-2026-014",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
curl "https://heyalink.com/api/emploi/v1/offres?limite=100" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/emploi/v1/offres?limite=100", {
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/offres?limite=100');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get(
"https://heyalink.com/api/emploi/v1/offres?limite=100",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
curl -X POST "https://heyalink.com/api/emploi/v1/offres/CC-2026-014/pourvue" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/emploi/v1/offres/CC-2026-014/pourvue", {
method: "POST",
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/offres/CC-2026-014/pourvue');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/emploi/v1/offres/CC-2026-014/pourvue",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
Les demandes de sous-traitance
Depuis la v1.13.0, l'API Emploi publie aussi les demandes de sous-traitance de votre page, avec les mêmes règles que
sur Heyalink : la demande paraît au nom de la page, publiée par son titulaire, avec sa publication dans le fil ; le nombre
de demandes ouvertes à la fois suit la formule de la page (au-delà : 403) ; fermer libère la place et prévient les
candidats ; supprimer est définitif. Droits : sous_traitance:lecture (lire les demandes et leurs candidatures) et
sous_traitance:ecriture (publier, modifier, fermer, rouvrir, supprimer).
| Appel | Ce qu'il fait |
|---|---|
GET /sous-traitance |
les demandes de la page, les plus récentes d'abord (limite, curseur) |
POST /sous-traitance |
publie une demande : 201 et la demande, avec son id |
GET /sous-traitance/{demande} |
la demande et son état (ouverte, fermee, masquee_par_la_moderation) |
PATCH /sous-traitance/{demande} |
modifie les blocs envoyés, chacun entier |
POST /sous-traitance/{demande}/fermer |
ferme : plus de candidatures, la place se libère |
POST /sous-traitance/{demande}/rouvrir |
rouvre, dans la limite de la formule |
DELETE /sous-traitance/{demande} |
supprime, définitivement : 204 |
GET /sous-traitance/{demande}/candidatures |
les candidatures reçues, en lecture |
Les champs sont ceux des blocs de Heyalink : titre (5 à 80 caractères), metier, ville et pays_code (absent :
la France), debut (date avec debut_le, ou des_que_possible), duree_nombre et duree_unite (jours,
semaines, mois), description (20 caractères au moins) ; facultatifs : budget_mode (montant ou a_discuter),
budget_montant (en euros HT) et budget_unite (forfait, jour, m2), decennale, rc_pro, garantie_autre.
Un champ refusé répond 422, champ par champ (errors, violations). Les photos et les documents s'ajoutent sur
Heyalink. dry_run et une clé de bac à sable vérifient tout et n'écrivent rien.
Retenir ou ne pas retenir une candidature reste un geste du gérant, sur Heyalink : l'API lit les candidatures sans les marquer vues.
curl -X POST "https://heyalink.com/api/emploi/v1/sous-traitance" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{
"titre": "Pose de 400 m² de plaques de plâtre",
"metier": "Plaquiste",
"ville": "Toulouse",
"debut": "des_que_possible",
"duree_nombre": 3,
"duree_unite": "semaines",
"description": "Cloisons et doublages d’un plateau de bureaux, accès par monte-charge.",
"budget_mode": "a_discuter"
}'
const reponse = await fetch("https://heyalink.com/api/emploi/v1/sous-traitance", {
method: "POST",
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"titre": "Pose de 400 m² de plaques de plâtre",
"metier": "Plaquiste",
"ville": "Toulouse",
"debut": "des_que_possible",
"duree_nombre": 3,
"duree_unite": "semaines",
"description": "Cloisons et doublages d’un plateau de bureaux, accès par monte-charge.",
"budget_mode": "a_discuter"
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/sous-traitance');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"titre": "Pose de 400 m² de plaques de plâtre",
"metier": "Plaquiste",
"ville": "Toulouse",
"debut": "des_que_possible",
"duree_nombre": 3,
"duree_unite": "semaines",
"description": "Cloisons et doublages d’un plateau de bureaux, accès par monte-charge.",
"budget_mode": "a_discuter"
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/emploi/v1/sous-traitance",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"titre": "Pose de 400 m² de plaques de plâtre",
"metier": "Plaquiste",
"ville": "Toulouse",
"debut": "des_que_possible",
"duree_nombre": 3,
"duree_unite": "semaines",
"description": "Cloisons et doublages d’un plateau de bureaux, accès par monte-charge.",
"budget_mode": "a_discuter",
},
)
print(reponse.status_code, reponse.text)
Envoyer par lot
Pour synchroniser toutes vos offres, envoyez jusqu'à 100 offres et 100 retraits par appel. Chaque offre a sa propre réponse : une offre refusée n'empêche pas les autres.
La réponse donne un bilan (créées, modifiées, retirées, refusées) et, pour chaque offre, son
statut (201, 200 ou 422) avec le message d'erreur s'il y en a un.
La liste complète. POST /offres/synchronisation reçoit toutes vos références en ligne :
chaque offre de l'API qui n'y est pas est archivée. Une liste vide n'archive rien, sauf avec
"confirmer_liste_vide": true : une erreur d'envoi ne vide pas votre page.
curl -X POST "https://heyalink.com/api/emploi/v1/offres/lot" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{
"offres": [
{
"reference": "CC-2026-014",
"titre": "Chef de chantier",
"description": "…",
"lieu": "Toulouse"
},
{"reference": "MAC-2026-002", "titre": "Maçon", "description": "…", "lieu": "Albi"}
],
"retirer": ["CC-2025-099"]
}'
const reponse = await fetch("https://heyalink.com/api/emploi/v1/offres/lot", {
method: "POST",
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"offres": [
{
"reference": "CC-2026-014",
"titre": "Chef de chantier",
"description": "…",
"lieu": "Toulouse"
},
{
"reference": "MAC-2026-002",
"titre": "Maçon",
"description": "…",
"lieu": "Albi"
}
],
"retirer": [
"CC-2025-099"
]
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/offres/lot');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"offres": [
{
"reference": "CC-2026-014",
"titre": "Chef de chantier",
"description": "…",
"lieu": "Toulouse"
},
{
"reference": "MAC-2026-002",
"titre": "Maçon",
"description": "…",
"lieu": "Albi"
}
],
"retirer": [
"CC-2025-099"
]
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/emploi/v1/offres/lot",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"offres": [
{
"reference": "CC-2026-014",
"titre": "Chef de chantier",
"description": "…",
"lieu": "Toulouse",
},
{
"reference": "MAC-2026-002",
"titre": "Maçon",
"description": "…",
"lieu": "Albi",
},
],
"retirer": [
"CC-2025-099",
],
},
)
print(reponse.status_code, reponse.text)
curl -X POST "https://heyalink.com/api/emploi/v1/offres/synchronisation" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{"references": ["CC-2026-014", "MAC-2026-002"]}'
const reponse = await fetch("https://heyalink.com/api/emploi/v1/offres/synchronisation", {
method: "POST",
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
body: JSON.stringify({
"references": [
"CC-2026-014",
"MAC-2026-002"
]
}),
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/offres/synchronisation');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"references": [
"CC-2026-014",
"MAC-2026-002"
]
}
JSON,
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post(
"https://heyalink.com/api/emploi/v1/offres/synchronisation",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
"Content-Type": "application/json",
},
json={
"references": [
"CC-2026-014",
"MAC-2026-002",
],
},
)
print(reponse.status_code, reponse.text)
Sans développement : votre page carrières, votre logiciel, votre flux
Sur l'écran API Emploi, collez une adresse https://. Heyalink reconnaît seul ce que c'est :
| Vous collez | Heyalink lit |
|---|---|
| votre page carrières | les offres balisées schema.org JobPosting de la page et de ses pages d'offre, et votre sitemap |
boards.greenhouse.io/… |
l'API publique Job Board de Greenhouse |
jobs.lever.co/… |
l'API publique Postings de Lever |
….recruitee.com |
l'API publique de votre page Recruitee |
careers.smartrecruiters.com/… |
l'API publique Posting de SmartRecruiters |
jobs.ashbyhq.com/… |
l'API publique Job Postings d'Ashby |
| un flux d'offres | XML des jobboards, RSS, JSON, JSON-LD (formats ci-dessous) |
Les formats de flux compris.
- XML des jobboards :
<source><job>…</job></source>, et aussi<jobs><job>,<offres><offre>,<positions><position>. Un XML qui déclare unDOCTYPEou des entités est refusé. - RSS : chaque
<item>est une offre (<guid>pour la référence,<title>,<description>,<link>). Sans lieu, la ville de la page est prise. - JSON : une liste d'offres, ou un objet
{"offres": […]}(aussijobs,data,items,results). - JSON-LD schema.org
JobPosting(seul, en liste ou dans@graph) :identifier,title,description,jobLocation.address.addressLocality,employmentType,baseSalary,url,validThrough.
| Champ Heyalink | Noms lus dans le flux (sans tenir compte des majuscules) |
|---|---|
| référence | referencenumber, reference, ref, id, identifier, guid, jobid, job_id, requisitionid |
| titre | title, titre, intitule, name, jobtitle, poste |
| description | description, content, contenu, summary, texte, body |
| lieu | city, ville, lieu, location, commune, addresslocality, joblocation |
| type de contrat | jobtype, type_contrat, typecontrat, contract, contrat, employmenttype |
| salaire | salary, salaire, basesalary, remuneration |
| métier | category, metier, occupationalcategory, categorie |
| secteur | industry, secteur |
| lien de candidature | url, link, lien, applyurl, apply_url, lien_candidature (https:// seulement) |
Une offre sans référence ou sans titre est sautée. Une offre mal remplie (sans description, par exemple) est notée dans le journal et n'est pas retirée pour autant. 500 offres au plus par flux, 5 Mo au plus.
D'abord, prouvez que la source est la vôtre. Pour que personne ne publie vos offres à votre place, Heyalink ne lit une source qu'une fois prouvé qu'elle vous appartient. L'écran API Emploi vous donne un jeton propre à la source, à poser d'une de ces façons, puis cliquez « Vérifier » :
- sur votre site, une balise dans l'en-tête de votre page carrières ou de votre page d'accueil :
<meta name="heyalink-verification" content="VOTRE-JETON">; - ou un fichier texte
https://votre-site/.well-known/heyalink.txtqui contient le jeton ; - pour un logiciel de recrutement, le jeton écrit dans la description d'une de vos offres publiées.
Si votre logiciel ne permet pas de poser le jeton, la source ne peut pas être lue : branchez-vous par l'API (plus haut), qui publie vos offres avec votre clé.
Laissez le jeton en place : Heyalink le revérifie chaque semaine. S'il disparaît, la source n'est plus lue et vous êtes prévenu par courriel.
Chaque lecture compare tout : une offre nouvelle est créée, une offre modifiée mise à jour,
une offre disparue de chez vous archivée (jamais effacée : si elle revient, elle revient avec son
adresse et ses candidatures). Une offre dont validThrough est passée est archivée « expirée » ;
une offre marquée pourvue (jobStatus: filled) est archivée « pourvue ».
Prudence en cas de panne : une lecture en erreur ne retire rien ; une source qui ne rend soudain plus aucune offre n'est vidée qu'au passage suivant, si elle est toujours vide. Au bout de trois erreurs de suite, ou dès qu'elle se vide, vous êtes prévenu par courriel.
Fraîcheur : Heyalink relit votre source toutes les 10 minutes au plus vite, plus rarement si
elle ne change pas (jusqu'à 6 heures), en requêtes conditionnelles (ETag, Last-Modified) pour
ne télécharger que ce qui change. Il respecte votre robots.txt et son Crawl-delay, ne lit que
les sitemaps de votre propre site (cinq au plus par passage), et s'annonce comme HeyalinkBot.
« Synchroniser maintenant » se demande une fois toutes les cinq minutes au plus.
Tout de suite, si vous voulez :
- l'adresse de mise à jour immédiate de votre source (écran API Emploi, « Mise à jour immédiate ») : appelez-la à chaque changement, Heyalink relit votre source dans la minute ;
- Greenhouse : un webhook « Job Post Created, Updated, Deleted » vers l'adresse donnée, avec le secret donné (signature vérifiée) ;
- WebSub : si votre flux annonce un hub, Heyalink s'y abonne seul, avec un secret propre au
hub (signatures
sha1,sha256,sha384ousha512acceptées).
<?xml version="1.0" encoding="utf-8"?>
<source>
<publisher>Mon entreprise</publisher>
<job>
<referencenumber>CC-2026-014</referencenumber>
<title><![CDATA[Chef de chantier gros œuvre]]></title>
<city>Toulouse</city>
<description><![CDATA[<p>Vous dirigez deux équipes.</p>]]></description>
<jobtype>CDI</jobtype>
<salary>38 000 € par an</salary>
<url>https://carrieres.votre-site.fr/offres/CC-2026-014</url>
</job>
</source>
curl -X POST "https://heyalink.com/api/emploi/v1/sources/12/relire/VOTRE-SIGNATURE"
const reponse = await fetch("https://heyalink.com/api/emploi/v1/sources/12/relire/VOTRE-SIGNATURE", {
method: "POST",
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/sources/12/relire/VOTRE-SIGNATURE');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.post("https://heyalink.com/api/emploi/v1/sources/12/relire/VOTRE-SIGNATURE")
print(reponse.status_code, reponse.text)
Les webhooks
Plutôt que d'interroger Heyalink, faites-vous prévenir. Sur l'écran API Emploi, ajoutez une
adresse https:// de votre site (cinq au plus) et choisissez ses événements. Une adresse de
l'API Emploi n'est prévenue que des offres d'emploi : elle n'apprend rien des formations.
| Événement | Quand |
|---|---|
annonce.publiee |
l'offre est en ligne (créée, revenue d'une archive, ou sortie d'attente) |
annonce.en_attente |
l'offre est enregistrée mais attend hors ligne : plafond de facture atteint ou facture impayée (Grands comptes) |
annonce.refusee |
la modération de Heyalink l'a masquée ou retirée |
annonce.expiree |
sa source (flux, page carrières) la dit échue ; depuis le 07/11/2026, une offre envoyée par l'API n'expire plus |
annonce.archivee |
elle est archivée |
annonce.pourvue |
elle est marquée pourvue |
annonce.fermee |
un gérant l'a fermée (sur Heyalink ou par …/fermer) ; elle se rouvre |
annonce.rouverte |
une annonce fermée est de nouveau en ligne |
annonce.supprimee |
un gérant l'a supprimée sur Heyalink, définitivement |
annonce.piece_refusee |
la modération a refusé une photo ou un PDF de l'annonce ; donnees.piece porte id, type (photo ou document) et nom |
ping |
l'essai envoyé depuis l'écran API Emploi |
Une adresse peut être une adresse de test : elle ne reçoit que les événements de vos offres
de test (clé hl_emploi_test_), et une vraie adresse que ceux de vos vraies offres, jamais les
uns chez les autres. Un événement de test porte "bac_a_sable": true dans son corps signé et
l'en-tête Heyalink-Bac-A-Sable: oui. Si l'une de vos adresses accumule trop de livraisons en
attente (panne de votre côté), les nouvelles ne sont plus préparées jusqu'à ce qu'elle réponde.
Heyalink envoie un POST en JSON :
Vérifiez la signature avant de croire un appel. L'en-tête
Heyalink-Signature: t=<horodatage>,v1=<signature> porte un HMAC-SHA256, calculé avec le secret
de l'adresse (affiché une seule fois à sa création) sur <horodatage>.<corps brut>. Refusez un
horodatage de plus de cinq minutes : un appel rejoué plus tard sera refusé.
Répondez par un statut 2xx dans les 10 secondes. Sinon, Heyalink réessaie après 1, 5, 30
minutes, puis 2 h, 6 h et 24 h ; Heyalink-Livraison identifie la livraison, pour ne pas traiter
deux fois la même. Une adresse en échec 20 fois de suite est désactivée.
{
"id": "evt_8f3k2m1q9x0a7b6c5d4e",
"evenement": "annonce.refusee",
"cree_le": "2026-10-19T14:02:11+02:00",
"bac_a_sable": false,
"donnees": {
"nature": "offre",
"reference": "CC-2026-014",
"titre": "Chef de chantier",
"motif": null,
"adresse": "https://heyalink.com/emplois/chef-de-chantier-12"
}
}
[$t, $v1] = sscanf($_SERVER['HTTP_HEYALINK_SIGNATURE'], 't=%d,v1=%s');
$corps = file_get_contents('php://input');
$attendu = hash_hmac('sha256', $t.'.'.$corps, getenv('HEYALINK_SECRET'));
if (! hash_equals($attendu, (string) $v1) || abs(time() - $t) > 300) {
http_response_code(400);
exit;
}
// corpsBrut : le corps reçu, tel quel (avant tout JSON.parse).
const [, t, v1] = req.get('Heyalink-Signature').match(/t=(\d+),v1=([a-f0-9]+)/);
const attendu = crypto.createHmac('sha256', process.env.HEYALINK_SECRET)
.update(`${t}.${corpsBrut}`)
.digest('hex');
const valide = attendu.length === v1.length
&& crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1))
&& Math.abs(Date.now() / 1000 - Number(t)) <= 300;
# entete : l'en-tête Heyalink-Signature ; corps_brut : le corps reçu, en octets.
t, v1 = (partie.split('=', 1)[1] for partie in entete.split(','))
attendu = hmac.new(os.environ['HEYALINK_SECRET'].encode(),
t.encode() + b'.' + corps_brut, hashlib.sha256).hexdigest()
valide = hmac.compare_digest(attendu, v1) and abs(time.time() - int(t)) <= 300
Le serveur MCP (agents d'IA)
Un agent d'IA (Claude, ChatGPT, ou votre propre agent) peut publier et tenir à jour vos offres
par le Model Context Protocol : POST https://heyalink.com/api/emploi/v1/mcp, transport « Streamable HTTP », avec la
même clé et les mêmes droits que l'API (Authorization: Bearer hl_emploi_live_…). Une clé
d'essai ne publie rien.
Outils, ceux de l'API Emploi seulement : offres_lister, offre_publier, offre_archiver,
offre_pourvue, offre_supprimer.
{
"mcpServers": {
"heyalink-emploi": {
"type": "http",
"url": "https://heyalink.com/api/emploi/v1/mcp",
"headers": { "Authorization": "Bearer hl_emploi_live_VOTRECLE" }
}
}
}
Les erreurs
Une erreur répond au format standard RFC 9457 (application/problem+json), avec un message
en français lisible tel quel :
violations dit, pour chaque champ refusé, la règle qui a échoué et une valeur valide : de quoi
corriger sans chercher.
| Code | Signification | Que faire |
|---|---|---|
| 200, 201 | modifiée, créée | rien |
| 204 | retirée | rien |
| 304 | rien n'a changé depuis votre ETag |
garder ce que vous avez |
| 400 | requête mal formée (Idempotency-Key trop longue, par exemple) |
lire detail |
| 401 | clé absente, inconnue, révoquée ou expirée | vérifier l'en-tête, recréer une clé |
| 403 | clé de l'API Formation, page sans la formule Grands comptes, droit manquant, adresse IP non autorisée, ou domaine pas encore prouvé | lire detail |
| 404 | référence inconnue (lecture seulement) | vérifier la référence |
| 409 | la même Idempotency-Key est encore en cours |
attendre sa réponse |
| 422 | offre refusée : champ manquant ou trop long, lien bloqué, offre retirée par la modération, ou Idempotency-Key déjà prise |
lire errors, champ par champ |
| 429 | trop d'appels | attendre Retry-After secondes, ou passer par /lot |
Erreur 400
La requête est mal formée : lisez detail, il dit quoi corriger.
Erreur 401
La clé est absente, mal copiée, révoquée ou expirée. Vérifiez l'en-tête
Authorization: Bearer hl_emploi_live_… ; au besoin, créez une nouvelle clé sur l'écran API
Emploi.
Erreur 403
detail dit laquelle de ces raisons s'applique : la clé appartient à l'API Formation (elle
n'ouvre pas l'API Emploi) ; la page n'a pas, ou plus, la formule Grands comptes ; la clé n'a pas le droit
demandé (par exemple offres:ecriture) ; l'appel vient d'une adresse IP que la clé n'autorise
pas ; ou la page n'a pas encore prouvé son domaine (publication pour de bon).
Erreur 404
La référence n'existe pas pour votre page. Vérifiez-la ; un PUT la crée.
Erreur 409
Une requête avec la même Idempotency-Key est encore en cours : attendez sa réponse avant de
rejouer.
Erreur 422
L'offre est refusée : errors donne le message champ par champ. Corrigez puis renvoyez.
Erreur 429
Trop d'appels pour cette clé. Attendez le nombre de secondes donné par Retry-After, ou
regroupez vos offres avec /lot (100 par appel).
Une offre masquée par la modération de Heyalink le reste : la republier répond 422, et son
etat vaut masquee_par_la_moderation.
{
"type": "https://heyalink.com/developpeurs/api/emploi#erreur-422",
"title": "Annonce refusée",
"status": 422,
"detail": "Le champ titre est obligatoire.",
"instance": "/api/emploi/v1/offres/CC-2026-014",
"errors": { "titre": ["Le champ titre est obligatoire."] },
"violations": [
{
"champ": "titre",
"regle": "required",
"message": "Le champ titre est obligatoire.",
"exemple": "Chef de chantier gros œuvre"
}
]
}
Le journal
GET /journal rend les 100 derniers appels et lectures de sources de l'API Emploi, avec leur
statut et leur message : une clé ne lit que le journal de son API. Il se lit avec une clé qui a
le droit offres:ecriture. Le même journal se lit sur l'écran API Emploi. Il est gardé 90
jours ; le journal de test (requêtes et réponses des clés d'essai, secrets masqués) l'est 7
jours.
Retirer une offre se rejoue sans risque : la réponse est 204, même si elle était déjà retirée.
curl "https://heyalink.com/api/emploi/v1/journal" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/emploi/v1/journal", {
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/journal');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.get(
"https://heyalink.com/api/emploi/v1/journal",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
curl -X DELETE "https://heyalink.com/api/emploi/v1/offres/MAC-2026-002" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
const reponse = await fetch("https://heyalink.com/api/emploi/v1/offres/MAC-2026-002", {
method: "DELETE",
headers: {
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
});
console.log(reponse.status, await reponse.text());
$ch = curl_init('https://heyalink.com/api/emploi/v1/offres/MAC-2026-002');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer hl_emploi_live_VOTRECLE',
],
CURLOPT_RETURNTRANSFER => true,
]);
$reponse = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $reponse, PHP_EOL;
import requests
reponse = requests.delete(
"https://heyalink.com/api/emploi/v1/offres/MAC-2026-002",
headers={
"Authorization": "Bearer hl_emploi_live_VOTRECLE",
},
)
print(reponse.status_code, reponse.text)
Versions et journal des changements
L'API Emploi est en v1 (https://heyalink.com/api/emploi/v1). Ce contrat est stable : la v1 n'évolue que de façon
compatible (un champ ou un appel de plus, jamais un champ retiré ni un sens changé). Une rupture
passerait en v2, à une autre adresse, annoncée à l'avance. La description complète, à jour, est
la spécification OpenAPI (https://heyalink.com/api/emploi/v1/openapi.json), qui fait foi.
| Version | Date | Changements |
|---|---|---|
| 1.13.0 | 08/11/2026 | Changement compatible (rien de retiré ni de renommé). Les demandes de sous-traitance de la page : GET et POST /sous-traitance, GET, PATCH et DELETE /sous-traitance/{demande}, POST …/fermer et …/rouvrir, GET …/candidatures (en lecture). Deux droits de plus, sous_traitance:lecture et sous_traitance:ecriture (une clé d'avant ne les a pas : en créer une nouvelle). Cinq webhooks : sous_traitance.publiee, .fermee, .rouverte, .supprimee, .candidature_recue |
| 1.12.0 | 07/11/2026 | Changement compatible (rien de retiré ni de renommé). Photos et PDF de l'annonce : media[] dans la lecture (id, type, nom, url, taille, ordre, statut : verification, publiee ou refusee), POST …/pieces, PUT …/pieces/ordre, DELETE …/pieces/{piece}, et le webhook annonce.piece_refusee. Chaque pièce est lue par la modération avant d'être montrée aux membres. Une annonce importée n'en porte pas |
| 1.11.0 | 07/11/2026 | Changement compatible (rien de retiré ni de renommé). Fermer et rouvrir : POST /offres/{reference}/fermer et …/rouvrir ; l'aperçu tel qu'un membre le voit : GET /offres/{reference}/apercu. Deux états de plus (fermee, retiree) et trois webhooks (annonce.fermee, annonce.rouverte, annonce.supprimee). Une annonce supprimée sur Heyalink par un gérant ne revient jamais : la même référence répond 409 annonce_supprimee ; une annonce fermée renvoyée reste fermée. Les services de la page, bloc par bloc : GET /services, POST /services (un brouillon), GET /services/{id}, PATCH /services/{id}/blocs/{bloc} (seuls les champs du bloc changent ; photos et PDF en multipart), GET /services/{id}/apercu, POST /services/{id}/publication, POST /services/{id}/fermeture, POST /services/{id}/reouverture, DELETE /services/{id}. La lecture suit le droit de lecture de la clé, l'écriture son droit d'écriture. Les trois mêmes webhooks disent aussi le geste de la page sur un service (nature service, référence : l'identifiant du service), et annonce.publiee sa publication |
| 1.10.0 | 07/11/2026 | Plus de date de fin : date_expiration reste accepté mais est ignoré (aucune erreur, aucun effet) et vaut toujours null dans les réponses ; une offre reste en ligne jusqu'à son archivage (DELETE ou statut). Une date reçue avant ne ferme plus l'offre. Le webhook annonce.expiree ne vise plus que les offres reprises d'une source (flux, page carrières) que la source dit échues. Aucun champ retiré ni renommé |
| 1.9.0 | 07/11/2026 | Changement compatible (rien de retiré ni de renommé, aucun sens changé). La fiche de l’offre : quatre champs facultatifs description_poste, description_missions, description_profil, description_avantages (les blocs de la fiche ; description reste exigée) et duree_nombre, duree_unite (la durée du contrat). Le texte salaire reste accepté ; sans salaire_min ni salaire_max, il donne les trois valeurs du salaire seulement quand il suit une forme sûre (« Mensuel de 2100.0 Euros à 2500.0 Euros », « 2 200 à 2 500 € par mois »), sinon il s’affiche tel quel. Mise à jour d’une offre déjà publiée (PUT sur la même référence) : un champ absent ne change plus rien, un champ obligatoire envoyé vide est refusé (422) ; une création exige toujours titre, description et lieu. Une offre publiée par l’API s’affiche dans la fiche exactement comme une offre saisie sur heyalink |
| 1.8.0 | 06/11/2026 | Aucun changement pour l'API Emploi : la version suit celle de l'API Formation (la fiche Formation) |
| 1.7.0 | 30/10/2026 | Documentation seule : elle dit la règle d'accès en vigueur depuis le 25/10/2026 : l'API Emploi est comprise dans la formule Grands comptes ; l'API elle-même ne change pas |
| 1.7.0 | 29/10/2026 | Dans la réponse, secteur_de_recherche : le secteur (un des dix) sous lequel la offre se trouve dans les filtres de recherche de Heyalink, lu depuis la famille ; aucun champ retiré, aucun sens changé |
| 1.6.0 | 28/10/2026 | Données riches, toutes facultatives : metier_code, famille_code, code_rome, experience_mois, temps_de_travail, teletravail, alternance, salaire_min, salaire_max, salaire_periode (listes fermées, 422 hors liste) ; dans la réponse, ces champs plus secteur et champs_deduits ; bloc signalements (champs ignorés, champs recommandés absents, valeurs déduites, incohérences) dans chaque publication et chaque résultat d'un lot ; le temps de travail, l'expérience, le télétravail et le salaire en nombres sont lus aussi dans les pages carrières balisées et les flux ; aucun champ retiré, aucun sens changé |
| 1.5.0 | 26/10/2026 | État en_attente et champ attente (motif plafond ou impaye, date de parution au plus tard) pour les annonces d'un Grand compte retenues par le plafond de facture ou un impayé ; webhook annonce.en_attente ; une annonce en attente se relit par sa référence et figure dans la liste |
| 1.4.0 | 21/10/2026 | Deux API distinctes, l'API Emploi (/api/emploi/v1) et l'API Formation (/api/formation/v1), chacune avec ses clés (hl_emploi_live_, hl_emploi_test_), sa spécification, ses collections, ses webhooks, son journal et ses outils MCP ; une clé de l'autre API reçoit 403 ; cle.api dans GET /moi ; l'ancienne adresse /api/entreprises/v1 et les anciennes clés restent servies jusqu'à leur remplacement |
| 1.3.0 | 19/10/2026 | Domaines prouvés (/domaines) : exigés pour publier pour de bon, et les liens des annonces doivent y mener ; adresses de webhook de test, champ bac_a_sable et en-tête Heyalink-Bac-A-Sable ; la validation à blanc vaut aussi pour le serveur MCP ; remplacement d'urgence d'une clé ; limite d'appels propre aux clés d'essai ; le journal demande un droit de publication ; le secret OAuth ne passe plus dans l'adresse |
| 1.2.0 | 19/10/2026 | Bac à sable complet (annonces de test listables, effacées après 7 jours), validation à blanc (dry_run), violations dans les erreurs, messages en anglais (Accept-Language), route sante, journal de test, données d'exemple, collections Postman et Bruno, « Tester ma source » |
| 1.1.0 | 19/10/2026 | Clés hl_live_ et hl_test_, droits fins, durée de vie, adresses IP, rotation, OAuth 2.0, Idempotency-Key, en-têtes RateLimit, erreurs RFC 9457, curseur, ETag, webhooks signés, OpenAPI 3.1, serveur MCP, preuve de propriété des sources |
| 1.0.0 | 19/10/2026 | Offres d'emploi et formations par référence, lot, synchronisation, LHEO, sources lues sans développement |