API pour partenaires ATS

Cette API permet aux partenaires ATS (Applicant Tracking Systems) d'intégrer Omogen comme service tiers pour gérer les entretiens de préqualification et de réactivation de leurs candidats. Elle fournit des endpoints pour synchroniser les offres d'emploi, créer des processus d'entretien, et des webhooks pour recevoir les rapports d'évaluation.

Télécharger la spec OpenAPI

Cette page est générée depuis une spec OpenAPI 3.0 disponible au téléchargement : 📄 JSON · 📄 YAML

Omogen automatise les entretiens téléphoniques avec les candidats via son agent conversationnel Alex, évalue leur adéquation avec les critères de sélection et génère des rapports détaillés pour aider les recruteurs dans leur prise de décision.

Configuration en self-serve

L'intégration se crée et se configure directement depuis l'application Omogen, sans passer par le support. Voir Créer l'intégration. En cas de question, vous pouvez tout de même nous contacter : gillian@omogen.ai.

Créer l'intégration

L'intégration « API personnalisée » se crée en quelques clics depuis l'application Omogen :

1. Ouvrez le menu Intégrations.
2. Cliquez sur Nouvelle intégration (+).
3. Choisissez Custom (l'intégration API personnalisée) dans la liste des connecteurs disponibles.
4. Renseignez les paramètres (voir ci-dessous), puis validez.

Dès la création, Omogen génère automatiquement vos deux clés (clé API et clé partenaire) : elles s'affichent dans la fiche de l'intégration, prêtes à copier. Vous n'avez plus à les demander au support.

Vous pouvez à tout moment rouvrir la fiche pour copier vos clés, modifier la configuration, ou désactiver l'intégration (la désactivation remplace la suppression : la configuration et l'historique sont conservés).

Paramètres de configuration

Les paramètres sont regroupés en trois sections.

Connexion

Paramètre	Éditable	Description
Clé API	❌ (généré)	Clé Bearer générée par Omogen — affichage et copie seulement.
Clé partenaire	❌ (généré)	Clé envoyée dans le header OM-PARTNER — affichage et copie seulement.
Identifiant d'agence (agency_id)	✅	Optionnel. Permet de distinguer plusieurs bridges qui partagent les mêmes clés (laisser vide si non utilisé).
URL de base (base_url)	✅	URL de votre endpoint qui recevra les webhooks (rapports, callbacks). Requise si les webhooks sont activés.

Webhooks

Paramètre	Description
Envoyer le webhook de rapport (send_report_created_webhook)	Active l'envoi d'un webhook vers votre endpoint à la génération d'un rapport (activé par défaut).
Format du rapport (report_format)	V2 (format API Partenaires, recommandé) ou default.
Méthode HTTP (webhook_http_method)	PUT (défaut) ou POST.
Headers du webhook (webhook_headers)	Paires clé/valeur ajoutées à chaque envoi (typiquement votre header d'authentification, ex. x-api-key).
Envoyer le webhook call_booked (send_call_booked_webhook)	Optionnel. Envoie aussi un webhook quand un candidat réserve un créneau.
URL call_booked dédiée (call_booked_webhook_url)	Optionnel. URL séparée pour les callbacks call_booked (par défaut, l'URL de base est utilisée).

Avancé

Paramètre	Description
URL de récupération des offres (job_fetch_url)	Pull flow uniquement. Template d'URL de votre endpoint, doit contenir le placeholder {job_id} (ex. https://api.partner.com/v1/jobs/{job_id}).
Headers de récupération (job_fetch_headers)	Pull flow. Paires clé/valeur ajoutées aux requêtes de récupération des offres (ex. Authorization).
Secret de signature (job_fetch_secret)	Pull flow. Secret partagé pour signer les requêtes en HMAC-SHA256 (voir Signature des requêtes).
Config de triage par défaut (default_triage_config_id)	Optionnel. UUID d'une configuration de triage pour router les candidats vers les offres via analyse du CV.

Quel flow choisir ?

Les paramètres « Avancé » ne concernent que le Flow 2 (Pull). Pour le Flow 1 (Push) et le Flow 3 (Direct), seules les sections Connexion et Webhooks sont nécessaires. Voir le comparatif des trois flows.

Authentification

L'authentification se fait via deux clés distinctes :

1. Une clé API Omogen transmise dans le header Authorization avec le format Bearer token
2. Une clé partenaire transmise dans le header OM-PARTNER pour identifier le partenaire ATS

Headers requis

Authorization: Bearer <API_KEY>
OM-PARTNER: <PARTNER_KEY>

Exemple

curl -X GET https://api.omogen.ai/api/v1/integration-partner/interview-params \
  -H "Authorization: Bearer sk_partner_abc123xyz..." \
  -H "OM-PARTNER: partner_xyz" \
  -H "Content-Type: application/json"

Gestion des clés

Les deux clés sont générées automatiquement lors de la création de l'intégration dans l'application Omogen. Chaque paire de clés est liée à une organisation spécifique. Vous les retrouvez à tout moment dans la fiche de l'intégration (menu Intégrations) — affichage et copie seulement, sans intervention du support.

• Clé partenaire : transmise dans le header OM-PARTNER, elle identifie l'origine des requêtes.
• Clé API : transmise dans le header Authorization au format Bearer token.

Flows d'intégration

Omogen propose trois modes d'intégration. Le choix dépend de qui détient le référentiel des offres et de la quantité d'informations que le partenaire peut envoyer en amont.

Comparatif des trois flows

Aspect	Flow 1 : Push	Flow 2 : Pull	Flow 3 : Direct
Qui détient les jobs ?	Le partenaire (ATS)	Le partenaire (ATS)	Omogen — jobs créées dans l'interface Omogen
Que faut-il envoyer dans la candidature ?	external_job_id + (optionnel) job_title / job_description	external_job_id uniquement (Omogen va chercher les détails)	job_opportunity_id (UUID Omogen)
Complexité côté partenaire	Faible (appels API sortants uniquement)	Moyenne (endpoint à implémenter)	Faible — pas de gestion de jobs côté partenaire
Pré-requis	Aucun endpoint à développer	Endpoint de lecture des jobs requis	Les jobs sont créées par les recruteurs dans l'interface Omogen
Configuration Omogen	Clés API uniquement	Clés API + URL endpoint + credentials partenaire	Clés API uniquement

Choix mutuellement exclusifs

Un appel à POST /applications (ou /applications/cv-only) ne peut utiliser qu'un seul mode de résolution de la job : soit external_job_id (Flows 1 & 2), soit job_opportunity_id (Flow 3), soit aucun des deux pour le mode triage. Envoyer external_job_id ET job_opportunity_id retourne 400 INVALID_PAYLOAD.

Flow 1 : Push (synchronisation par le partenaire)

Le partenaire ATS synchronise les offres d'emploi avant d'envoyer les candidatures.

Flow 2 : Pull (récupération par Omogen)

Le partenaire envoie directement les candidatures. Omogen récupère automatiquement les informations de l'offre d'emploi via un endpoint exposé par le partenaire.

Configuration du Flow 2 dans Omogen

Pour activer le Flow 2 (Pull), configurez les paramètres suivants dans la section Avancé de la fiche d'intégration (menu Intégrations → votre intégration → Modifier) :

Paramètre	Description
job_fetch_url	URL template de l'endpoint partenaire. Doit contenir le placeholder {job_id}, qu'Omogen remplace par l'external_job_id au moment de l'appel (ex : https://api.partner.com/v1/jobs/{job_id})
job_fetch_headers	Headers statiques injectés sur chaque requête (ex : {"Authorization": "Bearer <partner_api_key>"}). Utilisé pour l'authentification standard côté partenaire.
job_fetch_secret	Secret partagé utilisé pour signer chaque requête en HMAC-SHA256 (optionnel mais recommandé). Voir la section « Signature des requêtes » ci-dessous.

Endpoint à implémenter (Flow 2)

Endpoint : GET <job_fetch_url> où le placeholder {job_id} est remplacé par l'external_job_id envoyé dans POST /applications.

Headers envoyés par Omogen :

<headers configurés dans job_fetch_headers>
Content-Type: application/json
OM-OMOGEN-TIMESTAMP: <unix_timestamp>
OM-OMOGEN-REQUEST: <hmac_sha256_signature>

Signature des requêtes (recommandé)

Lorsque job_fetch_secret est configuré, Omogen signe chaque requête afin que le partenaire puisse vérifier l'origine de l'appel. Le partenaire doit recomposer la même signature de son côté et la comparer au header OM-OMOGEN-REQUEST.

timestamp = str(int(unix_time_seconds))
payload   = f"{timestamp}.{external_job_id}"
signature = HMAC_SHA256(secret=job_fetch_secret, message=payload).hexdigest()

Anti-rejeu

Le timestamp est en secondes Unix. Il est recommandé de rejeter les requêtes dont le timestamp s'écarte de plus de 5 minutes de l'heure serveur du partenaire afin de limiter les attaques par rejeu.

Réponse attendue (200 OK)

{
  "job_title": "Développeur Full Stack Python/React",
  "job_description": "Nous recherchons un développeur full stack expérimenté...",
  "metadata": {
    "department": "Engineering",
    "location": "Paris",
    "contract_type": "CDI"
  }
}

Champ	Type	Requis	Description
job_title	string	✅	Titre du poste
job_description	string	✅	Description complète du poste (min. 100 caractères recommandé)
metadata	object	❌	Champs additionnels libres (stockés comme metadata dans Omogen)

Codes d'erreur attendus côté partenaire

Code partenaire	Description	Code Omogen renvoyé au partenaire
200	Succès	Création/mise à jour de la job
404	Job non trouvée	400 JOB_FETCH_NOT_FOUND
4xx/5xx	Erreur serveur partenaire	502 JOB_FETCH_HTTP_ERROR
timeout/réseau	Erreur réseau	502 JOB_FETCH_NETWORK_ERROR
JSON invalide	Réponse non parsable	502 JOB_FETCH_INVALID_RESPONSE
200 sans job_title	Champ obligatoire manquant	502 JOB_FETCH_MISSING_TITLE

Flow 3 : Direct (jobs créées dans Omogen)

Pour les partenaires qui n'ont pas d'ATS et créent leurs offres directement dans l'interface Omogen, l'API accepte un job_opportunity_id (UUID Omogen) au lieu d'un external_job_id. Aucun mapping côté Omogen n'est créé — la candidature pointe directement sur la job existante.

Le job_opportunity_id est scopé à l'organisation : envoyer un UUID qui pointe sur une job appartenant à une autre organisation retourne 400 JOB_OPPORTUNITY_NOT_FOUND.

Lien d'invitation candidat

Pour les modes de déploiement où le candidat se planifie lui-même (pas d'appel sortant immédiat), Omogen génère un lien d'invitation au format https://agent.omogen.ai/invitation/{process_id}. Le candidat clique sur ce lien pour choisir un créneau d'entretien.

Modes de déploiement avec lien d'invitation

Mode	Comportement
email-invitation	Omogen envoie un email au candidat avec le lien
sms-invitation	Omogen envoie un SMS au candidat avec le lien
whatsapp-invitation	Omogen envoie un WhatsApp au candidat avec le lien
invitation-link-only	Omogen n'envoie rien — le partenaire affiche le lien dans sa propre interface

Quand utiliser invitation-link-only

Choisissez ce mode si vous voulez contrôler totalement la communication avec le candidat (par ex. l'afficher dans votre propre portail candidat ou votre dashboard de recruteur). Le processus est créé en statut active et expire automatiquement après 10 jours sans réservation, comme les autres modes invitation.

Récupérer le lien dans la réponse

POST /applications (et /applications/cv-only) renvoient le lien dans le champ data.invitation_link dès lors que le mode de déploiement résolu est un mode invitation :

{
  "success": true,
  "message": "Application synchronized and process created successfully",
  "data": {
    "process_id": "9b6e81e0-5736-4106-ba8b-86df6a43b663",
    "status": "in_progress",
    "invitation_link": "https://agent.omogen.ai/invitation/9b6e81e0-5736-4106-ba8b-86df6a43b663",
    "..." : "..."
  }
}

Pour les modes orientés appel (single-call, sms-then-call, 3-days, reactivation, whatsapp-then-call, cv-only), invitation_link vaut null : la page d'invitation existe mais le formulaire de réservation n'est pas activé pour ces processus, donc afficher le lien mènerait le candidat vers une page non fonctionnelle.

Référence des endpoints

La section suivante est générée automatiquement à partir de la spécification OpenAPI openapi-partenaires.yaml.

Get Interview Params

Get Interview Params

GET

/interview-params

Récupère les paramètres de configuration disponibles pour les entretiens.
Permet aux utilisateurs de choisir d'activer Omogen et de sélectionner un mode de déploiement.

⚠️ Les paramètres exacts peuvent être personnalisés pour améliorer l'expérience utilisateur dans l'ATS.

Authorizations

BearerToken

Clé API Omogen envoyée dans le header Authorization: Bearer <API_KEY>. Fournie par le support Omogen.

Type

HTTP (bearer)

+

OmPartner

Clé partenaire unique envoyée dans le header OM-PARTNER: <PARTNER_KEY>. Identifie l'ATS source.

Type

API Key (header: OM-PARTNER)

Parameters

Query Parameters

lang

Code langue des libellés retournés

Type

string

Valid values

"fr""en"

Default

"fr"

Responses

Paramètres récupérés avec succès

Content-Type

application/json

{

  

"success": true,

  

"data": {

  

  

"use_cases": [

  

  

  

{

  

  

  

  

"value": "string",

  

  

  

  

"label": "string"

  

  

  

}

  

  

],

  

  

"deployment_templates": [

  

  

  

{

  

  

  

  

"value": "string",

  

  

  

  

"label": "string",

  

  

  

  

"description": "string"

  

  

  

}

  

  

],

  

  

"report_limit": {

  

  

  

"default": 0,

  

  

  

"min": 0,

  

  

  

"max": 0,

  

  

  

"label": "string",

  

  

  

"description": "string"

  

  

},

  

  

"match_limit": {

  

  

  

"default": 0,

  

  

  

"min": 0,

  

  

  

"max": 0,

  

  

  

"label": "string",

  

  

  

"description": "string"

  

  

}

  

}

}

Sync a Job Offer

Sync a Job Offer

POST

/jobs

Synchronise une offre d'emploi dans Omogen. Le endpoint retourne immédiatement
(201 Created) avec l'id de la job et un edit_url. L'extraction des critères
de sélection et la génération du plan d'entretien se font de manière asynchrone
en arrière-plan.

ℹ️ Cet endpoint est utilisé uniquement dans le Flow 1 (Push). Dans le Flow 2,
les jobs sont créées automatiquement lors de la réception d'une candidature.

Idempotence : si external_job_id est fourni et qu'une job avec cet identifiant
existe déjà pour l'organisation, l'endpoint retourne 200 OK au lieu de 201 et
ne recrée pas la job.

Authorizations

BearerToken

Clé API Omogen envoyée dans le header Authorization: Bearer <API_KEY>. Fournie par le support Omogen.

Type

HTTP (bearer)

+

OmPartner

Clé partenaire unique envoyée dans le header OM-PARTNER: <PARTNER_KEY>. Identifie l'ATS source.

Type

API Key (header: OM-PARTNER)

Request Body

application/json

{

  

"job_title": "string",

  

"job_description": "string",

  

"external_job_id": "string"

}

Responses

Job déjà existante (idempotence sur external_job_id)

Content-Type

application/json

{

  

"success": true,

  

"message": "string",

  

"data": {

  

  

"job_opportunity_id": "string",

  

  

"edit_url": "string"

  

}

}

Sync an Application

Sync an Application (Create Interview Process)

POST

/applications

Crée ou met à jour un candidat et crée un processus d'entretien (process) pour celui-ci.
Le candidat sera contacté selon le mode de déploiement spécifié.

Comportement selon le flow

• Flow 1 (Push) : l'external_job_id doit correspondre à une job déjà synchronisée via POST /jobs.
• Flow 2 (Pull) : Omogen récupère automatiquement les infos de l'offre via l'endpoint du partenaire.
• Flow 3 (Direct) : envoyer job_opportunity_id (UUID Omogen) au lieu d'external_job_id quand la job a été créée dans l'interface Omogen.
• Mode triage : si aucun des deux IDs n'est fourni et que le mode triage est activé, Omogen utilise le CV pour déterminer automatiquement la job cible.

external_job_id et job_opportunity_id sont mutuellement exclusifs.

Pour un appel à cet endpoint qui n'inclut que le CV (sans données candidat),
utiliser plutôt POST /applications/cv-only.

CV du candidat (optionnel)

Le CV est facultatif sur cet endpoint. S'il est fourni, deux moyens sont
acceptés, exclusifs :

• cv_url : une URL publique vers le fichier ;
• cv_file : le contenu du fichier encodé en base64 (auquel cas
  cv_filename est requis).

Si les deux sont envoyés, cv_file (base64) est prioritaire.

Authorizations

BearerToken

Clé API Omogen envoyée dans le header Authorization: Bearer <API_KEY>. Fournie par le support Omogen.

Type

HTTP (bearer)

+

OmPartner

Clé partenaire unique envoyée dans le header OM-PARTNER: <PARTNER_KEY>. Identifie l'ATS source.

Type

API Key (header: OM-PARTNER)

Request Body

application/json

{

  

"external_application_id": "APP-456",

  

"external_job_id": "JOB-12345",

  

"external_candidate_id": "CAND-789",

  

"first_name": "Marie",

  

"last_name": "Dubois",

  

"email": "marie.dubois@example.com",

  

"phone": "+33612345678",

  

"use_case": "prequalification",

  

"deployment_template": "single-call",

  

"cv_url": "https://example.com/cv/marie-dubois.pdf"

}

Responses

Application déjà existante (idempotence)

Content-Type

application/json

{

  

"success": true,

  

"message": "string",

  

"data": {

  

  

"process_id": "string",

  

  

"status": "string",

  

  

"invitation_link": "string"

  

}

}

Sync a CV-only Application

Sync an Application from CV only

POST

/applications/cv-only

Crée un processus d'entretien à partir d'un CV seul. Omogen extrait automatiquement
les informations candidat (nom, prénom, email, téléphone) depuis le CV via un service
d'extraction. Si l'extraction échoue pour certains champs, les valeurs de secours
fournies dans la requête sont utilisées.

Format de la requête : multipart/form-data ou application/json.
Le CV peut être fourni soit en base64 via cv_file, soit via une URL publique via
cv_url. L'un des deux est obligatoire.

Extensions supportées : .pdf, .doc, .docx, .txt, .rtf.

Authorizations

BearerToken

Clé API Omogen envoyée dans le header Authorization: Bearer <API_KEY>. Fournie par le support Omogen.

Type

HTTP (bearer)

+

OmPartner

Clé partenaire unique envoyée dans le header OM-PARTNER: <PARTNER_KEY>. Identifie l'ATS source.

Type

API Key (header: OM-PARTNER)

Request Body

object

Contenu du CV encodé en base64. Exclusif avec cv_url — au moins l'un des deux est requis.

Format"byte"

URL publique vers le CV. Exclusif avec cv_file — au moins l'un des deux est requis.

Format"uri"

Nom du fichier avec extension (.pdf, .doc, .docx, .txt, .rtf)

Prénom de secours si l'extraction depuis le CV échoue

Nom de secours si l'extraction depuis le CV échoue

Email de secours si l'extraction depuis le CV échoue

Format"email"

Téléphone de secours si l'extraction depuis le CV échoue

ID de l'offre dans le système partenaire. Mutuellement exclusif avec
job_opportunity_id. Optionnel si mode triage ou si
job_opportunity_id est fourni.

UUID Omogen de la job (Flow 3 Direct). Mutuellement exclusif avec
external_job_id. Voir le schéma SyncApplicationRequest pour le détail.

Format"uuid"

Valid values"prequalification""reactivation"

Default"prequalification"

Mode de déploiement (mêmes valeurs que SyncApplicationRequest.deployment_template,
y compris invitation-link-only).

Responses

Application déjà existante (idempotence)

Content-Type

application/json

{

  

"success": true,

  

"message": "string",

  

"data": {

  

  

"process_id": "string",

  

  

"status": "string",

  

  

"invitation_link": "string"

  

}

}