Documentation Job offers
Job offers
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 :
curl https://heyalink.com/api/emploi/v1/sante
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.
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.
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"
}'
{
"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
}
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 :
curl "https://heyalink.com/api/emploi/v1/offres/CC-2026-014" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
curl "https://heyalink.com/api/emploi/v1/offres?limite=100" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
Le poste est pourvu : l'offre sort du site, archivée « pourvue ».
curl -X POST "https://heyalink.com/api/emploi/v1/offres/CC-2026-014/pourvue" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
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.
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.
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"]
}'
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/synchronisation" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE" \
-H "Content-Type: application/json" \
-d '{"references": ["CC-2026-014", "MAC-2026-002"]}'
This section is written in French; the OpenAPI 3.1 specification describes every field.