Documentation Start in 5 minutes
Start in 5 minutes
From the key to your first job offer online, with curl. Replace the key with yours; everything else copies as is.
Your key
Create it in your Key accounts space (the Jobs API comes with the Key accounts plan). It is shown only once: store it in your secrets manager.
export HEYALINK_CLE="hl_emploi_live_…"
Check it
The moi call tells you which page the key belongs to, its rights and your limits.
curl https://heyalink.com/api/emploi/v1/moi \
-H "Authorization: Bearer $HEYALINK_CLE"
{
"entreprise": { "nom": "Bâtisseurs de Garonne", "adresse": "https://heyalink.com/…" },
"cle": {
"nom": "Recruitment software", "api": "emploi", "debut": "hl_emploi_live_k3",
"droits": ["offres:lecture", "offres:ecriture"], "creee_le": "2026-10-28T10:12:00+01:00"
},
"limites": { "appels_par_minute": 300, "annonces_par_lot": 100 },
"success": true
}
Try a dry run
With dry_run=1, everything is checked and the answer is that of a real write, with "simulation": true. Nothing is published.
curl -X PUT "https://heyalink.com/api/emploi/v1/offres/CC-2026-014?dry_run=1" \
-H "Authorization: Bearer $HEYALINK_CLE" \
-H "Content-Type: application/json" \
-d @offre.json
Publish the offer
The same call, without dry_run. Your reference is the key of the listing: sending the same reference again updates it. The Idempotency-Key header protects against a double send for 24 hours.
curl -X PUT https://heyalink.com/api/emploi/v1/offres/CC-2026-014 \
-H "Authorization: Bearer $HEYALINK_CLE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7f3c2a9e-cc-2026-014" \
-d '{
"titre": "Structural works site manager",
"description": "<p>You lead two teams on multi-family housing sites.</p>",
"lieu": "Toulouse (31)",
"code_postal": "31000",
"type_contrat": "CDI",
"lien_candidature": "https://www.example.com/jobs/CC-2026-014"
}'
{
"offre": { "reference": "CC-2026-014", "etat": "en_ligne", "code_rome": "F1202", "adresse": "https://heyalink.com/…" },
"resultat": "creee",
"avertissements": []
}
Publishing paused? When a charge did not go through, or when the monthly cap is reached, the offer is saved with
"etat": "en_attente"and its reason; it goes live as soon as the payment goes through, or on the 1st of the next month at the latest.
Get notified
Every change to a listing (annonce.publiee, annonce.expiree…) arrives as a POST on your address, signed by the Heyalink-Signature: t=…,v1=… header. Check the signature, and reject anything older than 5 minutes.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function signatureValide(entete, corpsBrut, secret) {
const { t, v1 } = Object.fromEntries(
entete.split(',').map(p => p.split('='))
);
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const attendu = createHmac('sha256', secret)
.update(`${t}.${corpsBrut}`).digest('hex');
return timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}
That's it. Next: job offers, trainings, webhooks.