Aller au contenu

Documentation Offres d’emploi

Offres d’emploi

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.

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.

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

Vos choix sur les cookies

Avec votre accord, Heyalink mesure la fréquentation du site avec Google Analytics, et compte les vues des annonces sponsorisées pour les facturer à leurs annonceurs. Rien n'est déposé avant votre choix, et refuser ne change rien à l'usage du site. Votre choix est gardé six mois ; vous pouvez le changer à tout moment par « Gérer les cookies », en bas de page. En savoir plus

Personnaliser

Rien n'est déposé avant votre choix, et refuser ne change rien à l'usage du site. Votre choix est gardé six mois ; vous pouvez le changer à tout moment par « Gérer les cookies », en bas de page. En savoir plus

Choisissez catégorie par catégorie