Skip to content

Heyalink Developers Jobs API

Jobs API

Your job ads, published and kept up to date from your website or your recruitment software.

Quick start

  1. Create a key

    On the Jobs API screen of your page, a test key checks everything and publishes nothing.

    Log in to create a key
  2. Check that it answers

    A call to /moi returns your page and the key’s permissions.

    GET /moi
  3. Publish a job ad

    Send it first as a dry run, with the dry_run parameter: Heyalink answers without writing anything.

    See the example

Log in with an account that manages a business page to try the examples right here, in the sandbox.

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

  1. 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.
  2. 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.
  3. Vérifiez qu'elle marche :
  1. 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).
  2. Suivez le résultat dans le journal de l'écran API Emploi, ou par GET /journal.
Request
curl https://heyalink.com/api/emploi/v1/moi -H "Authorization: Bearer hl_emploi_live_VOTRECLE"

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 /moi la 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 : avec offres:…, elles ouvrent l'API Emploi. Leur remplacement donne une clé de l'API Emploi seule.
  • L'ancienne adresse commune /api/entreprises/v1 reste servie pour elles ; le cloisonnement des deux API y vaut aussi. Passez à https://heyalink.com/api/emploi/v1 à votre rythme.
Request
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"
      }'
Request
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"
Response JSON
{
  "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.

  1. Déclarez le domaine : POST /domaines avec {"domaine": "votre-site.fr"}, ou sur l'écran API Emploi. La réponse donne un jeton propre au domaine.
  2. Posez-le sur votre site, au choix : la balise <meta name="heyalink-verification" content="JETON"> dans la page d'accueil, ou un fichier https://votre-site.fr/.well-known/heyalink.txt qui contient le jeton.
  3. Vérifiez : POST /domaines/votre-site.fr/verification. domaine.prouve passe à 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.

Request
curl https://heyalink.com/api/emploi/v1/sante

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.

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épond 409, code annonce_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 par POST /offres/{reference}/rouvrir.
Request
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"
      }'
Response JSON
{
  "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
}
Request
curl "https://heyalink.com/api/emploi/v1/offres/CC-2026-014" \
  -H "Authorization: Bearer hl_emploi_live_VOTRECLE"
Request
curl "https://heyalink.com/api/emploi/v1/offres?limite=100" \
  -H "Authorization: Bearer hl_emploi_live_VOTRECLE"
Request
curl -X POST "https://heyalink.com/api/emploi/v1/offres/CC-2026-014/pourvue" \
  -H "Authorization: Bearer hl_emploi_live_VOTRECLE"

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.

Request
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"
      }'

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.

Request
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"]
      }'
Request
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"]}'

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 un DOCTYPE ou 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": […]} (aussi jobs, 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.txt qui 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, sha384 ou sha512 acceptées).
Code XML
<?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>
Request
curl -X POST "https://heyalink.com/api/emploi/v1/sources/12/relire/VOTRE-SIGNATURE"

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.

JSON JSON
{
  "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"
  }
}
Code
[$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;
}

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.

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

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

Request
curl "https://heyalink.com/api/emploi/v1/journal" \
  -H "Authorization: Bearer hl_emploi_live_VOTRECLE"
Request
curl -X DELETE "https://heyalink.com/api/emploi/v1/offres/MAC-2026-002" \
  -H "Authorization: Bearer hl_emploi_live_VOTRECLE"

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

Your cookie choices

With your consent, Heyalink measures site traffic with Google Analytics, and counts views of sponsored ads to bill their advertisers. Nothing is set before you choose, and declining changes nothing about how you use the site. Your choice is kept for six months; you can change it at any time with "Manage cookies" at the bottom of the page. Find out more

Customise

Nothing is set before you choose, and declining changes nothing about how you use the site. Your choice is kept for six months; you can change it at any time with "Manage cookies" at the bottom of the page. Find out more

Choose category by category