Connecter votre logiciel avec l’API

Avant de commencer

L’API permet à votre logiciel de recrutement de créer des campagnes, d’inviter des candidats et de lire leurs dossiers. Elle est incluse dans tous les packs.

Dans l’API, une campagne s’appelle interview et un entretien s’appelle session.

Le détail des champs de chaque route est dans la description OpenAPI (en anglais).

Créer une clé

Seuls le propriétaire et les administrateurs peuvent gérer les clés.

1. Ouvrez Accès API

   La page est dans le menu du compte, ou à l’adresse Paramètres, Accès API.

2. Créez la clé

   Créer une clé donne tous les accès. Personnaliser permet de choisir un nom, une date d’expiration et les accès.

3. Copiez la clé tout de suite

   Elle commence par dlv_. Minute ne garde pas la clé en clair : si vous la perdez, régénérez-la.

Vous pouvez avoir 10 clés actives au plus.

Appeler l’API

Envoyez la clé dans l’en-tête Authorization. Les réponses sont en JSON, sous la forme { "data": … }.

curl https://VOTRE-ADRESSE/api/v1/interviews \
  -H "Authorization: Bearer dlv_votre_cle"

Une clé est limitée à 60 requêtes par minute. Au-delà, l’API répond 429 avec l’en-tête Retry-After.

Les listes de campagnes et d’entretiens se lisent page par page : limit (de 1 à 100, 20 par défaut) et cursor. La réponse contient cursor, qui vaut null à la dernière page.

Accès et routes

Chaque clé a des accès. Une route refuse la clé avec l’erreur 403 INSUFFICIENT_SCOPE si l’accès manque. Les chemins ci-dessous sont à ajouter à /api/v1.

campaigns:read Campagnes, lecture

• GET /interviews : liste des campagnes
• GET /interviews/{id} : une campagne, avec ses questions
• GET /interviews/{id}/questions : ses questions
• GET /usage : l’usage de l’organisation

campaigns:write Campagnes, modification

• POST /interviews : créer une campagne (title obligatoire)
• PATCH /interviews/{id} : modifier une campagne
• DELETE /interviews/{id} : archiver une campagne
• POST /interviews/{id}/publish : publier
• POST /interviews/{id}/questions : ajouter des questions (1 à 100)
• PATCH /questions/{id} et DELETE /questions/{id} : modifier ou supprimer une question
• POST /interviews/{id}/sessions/end : terminer des entretiens en cours

candidates:read Candidats, lecture

• GET /interviews/{id}/candidates : candidats d’une campagne

candidates:write Candidats, invitation et modification

• POST /interviews/{id}/candidates : inviter des candidats
• PATCH /interviews/{id}/candidates/{candidateId} : modifier un candidat

reports:read Entretiens et dossiers, lecture

• GET /interviews/{id}/sessions : entretiens d’une campagne
• GET /sessions/{id} : un entretien, avec ses messages
• GET /sessions/{id}/report : le dossier d’un entretien

practices:read Entraînements, lecture

• GET /practices/{id} et GET /interviews/{id}/practices : répondent 410 PILOT_UNAVAILABLE. Le coaching n’est pas disponible.

Exemple : inviter des candidats

1. Créez la campagne

   curl -X POST https://VOTRE-ADRESSE/api/v1/interviews \
     -H "Authorization: Bearer dlv_votre_cle" \
     -H "Content-Type: application/json" \
     -d '{"title": "Téléconseiller"}'

2. Ajoutez les questions, puis publiez

   Appelez POST /interviews/{id}/questions, puis POST /interviews/{id}/publish. La réponse contient l’adresse publique de la campagne.

3. Invitez les candidats

   Le corps est un objet, ou une liste de 1 à 500 objets. name est obligatoire ; email, phone et notes sont facultatifs.

   curl -X POST https://VOTRE-ADRESSE/api/v1/interviews/ID/candidates \
     -H "Authorization: Bearer dlv_votre_cle" \
     -H "Content-Type: application/json" \
     -d '[{"name": "Awa Ndiaye", "email": "[email protected]"}]'

   Chaque candidat créé a un champ inviteUrl : c’est son lien personnel. Deux candidats qui ont la même adresse e-mail dans une requête n’en font qu’un. La campagne doit être publiée, sinon l’API répond 412.

4. Lisez les dossiers

   Appelez GET /interviews/{id}/sessions pour lister les entretiens, puis GET /sessions/{id}/report pour le dossier.

Être prévenu : les webhooks

Dans Paramètres, Accès API, ajoutez une adresse https:// et choisissez les événements : session.completed quand un entretien se termine, session.report_ready quand son dossier est prêt. Minute envoie un POST en JSON aux webhooks de tous les membres de l’organisation abonnés à l’événement.

{
  "id": "identifiant de l’envoi",
  "type": "session.report_ready",
  "created": 1760000000,
  "livemode": true,
  "data": { "sessionId": "…", "interviewId": "…" }
}

Le message ne contient que des identifiants : lisez le dossier avec GET /sessions/{id}/report. Vérifiez la signature avant de le traiter : X-Minute-Signature vaut v1= suivi du HMAC-SHA256 en hexadécimal de horodatage.corps, calculé avec le secret du webhook ; l’horodatage, en secondes, est dans X-Minute-Timestamp. Refusez un horodatage de plus de 5 minutes.

Répondez par un statut 2xx en moins de 10 secondes. Sinon Minute réessaie après 1 minute puis 10 minutes, 3 tentatives au plus. Le journal des derniers envois est sous la liste des webhooks ; Renvoyer relance un envoi avec le même id, que vous pouvez utiliser pour ignorer un doublon.

Les erreurs

Une erreur a la forme { "error": { "code": …, "message": … } }. Fiez-vous au code : le texte du message peut être en français ou en anglais.