API directe dans votre back-end

Le pattern le plus puissant. Votre application appelle l'API depuis votre serveur, vous rendez les résultats dans votre propre interface. Vous gardez le contrôle de l'UX, du cache (si vous en faites un), de la rétention. Jobydoo s'occupe de la couverture, de la déduplication et de la fraîcheur.

Pour qui

• Plateformes HR-tech qui ajoutent une fonction de recherche d'offres
• ATS internes ou outils RH d'entreprise
• Job boards de niche qui veulent une couverture plus large que leurs propres annonceurs
• Cabinets de recrutement avec un développeur ou un prestataire

Endpoint

POST https://api.jobydoo.io/api/v1/jobs

Authentification

Header Authorization: Bearer jdy_live_…. Utilisez une clé server depuis votre back-end uniquement. Gardez-la dans une variable d'environnement ou un secret manager — elle n'est affichée qu'une seule fois.

Exemple de requête

export JOBYDOO_API_KEY="jdy_live_replace_me"

curl --fail-with-body -X POST https://api.jobydoo.io/api/v1/jobs \
  -H "Authorization: Bearer $JOBYDOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "directeur industriel",
    "country": "FR",
    "city": "Lyon",
    "seniority": "director",
    "posted_within_days": 30,
    "max_results": 20
  }'

Paramètres

• q (string, requis) — titre du poste recherché, 2 à 200 caractères
• country (ISO-2, défaut FR) — pays d'exécution de la recherche
• city (string, optionnel) — ville pour scoper
• region (string, optionnel) — région
• remote (any | remote | hybrid | on_site, défaut any)
• seniority (junior | mid | senior | lead | director | vp | c-level, défaut senior)
• posted_within_days (1–60, défaut 30)
• max_results (1–500, défaut 20) — plafonné par resultsCap du plan
• credits (alias de max_results, plus explicite sur les plans à crédits)
• use_xray (boolean, défaut false) — active les sources gated. Plan Enterprise requis.
• use_stealth (boolean, défaut false) — autorise le rendu headless sur les plans qui l'incluent
• must_have, exclude — listes de mots-clés (max 10 chacune)
• target_companies — noms d'entreprises cibles (max 5)

Réponse

{
  "run_id": "5a86bdd2-…",
  "query": { ... },
  "results": [
    {
      "id": "…",
      "source": "greenhouse",
      "title": "Directrice industrielle",
      "company": { "name": "…", "domain": "…" },
      "location": { "city": "Lyon", "country_iso2": "FR", "remote": "hybrid" },
      "salary": { "min": 95000, "max": 120000, "currency": "EUR", "period": "yearly" },
      "posted_at": "2026-05-08T12:34:56Z",
      "apply_url": "https://…",
      "fit_score": 0.91
    },
    …
  ],
  "source_status": [ { "source": "…", "status": "ok", "count": 12 } ],
  "served_from_cache": false,
  "live_discovery": true,
  "counts": { "from_index": 4, "from_live": 16, "total": 20 },
  "quota": { "remaining": 14985, "plan": "pro", "model": "monthly-calls" },
  "latency_ms": 18247
}

Limites de débit

• Quota mensuel par plan — voir /pricing
• La découverte live est bornée côté serveur ; si la file est pleine, Jobydoo sert l'index canonique existant.
• Une seule clé peut être partagée par plusieurs services back-end internes ; le quota est commun.

Cache et fraîcheur

Jobydoo interroge d'abord son index canonique, puis lance une découverte live quand elle est disponible et utile. Les recherches live récentes sont mises en cache 48 h. Si le moteur live est saturé ou indisponible, la réponse reste utilisable avec les résultats de l'index et source_status indique la raison.

Erreurs

• 401 invalid_credentials — clé manquante, mal formée, ou révoquée
• 402 xray_not_in_plan — use_xray: true sur un plan qui ne l'inclut pas
• 402 subscription_inactive — paiement échoué ou abonnement annulé
• 429 quota_exceeded — appels mensuels épuisés (réinitialisation le 1er à 00:00 UTC)
• 429 credits_exhausted — crédits épuisés sur la fenêtre glissante (plan Dev)
• 502 unreachable | timeout | remote_error — moteur live indisponible et aucun résultat d'index disponible