Présélectionner un candidat

Mis à jour 29 septembre 2026

Une présélection est un entretien par IA construit à partir de l’un de vos modèles de présélection. Le candidat la passe quand il le souhaite, et les résultats reviennent dans Orbit. Les recruteurs envoient les présélections depuis Orbit. Cette page sert à les envoyer depuis votre propre système, par exemple quand un changement d’étape dans votre ATS doit inviter le candidat sans que personne n’ouvre Orbit.

Ce qu’il vous faut

• Une clé portant la portée Présélection, créée dans Orbit → Paramètres → Clés d’API. C’est une portée à part : une clé qui lit ou gère les offres répond 403 ici, et une clé de présélection ne peut pas lire les offres.
• Une offre gérée. La présélection fait partie de la gestion d’une offre, qu’un recruteur active dans Orbit. Sur une offre qui n’est pas gérée, la requête répond 409 avec ad_not_managed.
• Trois identifiants : le jobId du poste, l’identifiant du candidat sur ce poste et le templateId de l’un de vos modèles de présélection actifs.

export ORBIT_SCREENING_KEY="…une clé portant la portée Présélection…"

Inviter le candidat

curl -X POST https://api.wipperoz.com/v1/jobs/job_01J8Z3K9Q0EXAMPLE/candidates/app_01J9B2C3D4EXAMPLE/screening \
  -H "Authorization: Bearer $ORBIT_SCREENING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl_01J9C3D4E5EXAMPLE",
    "completeBy": "2026-10-02T00:00:00.000Z",
    "message": "Merci pour votre candidature. Cela prend environ quinze minutes.",
    "language": "fr"
  }'

• templateId est le seul champ obligatoire. Ce doit être l’un des modèles de présélection actifs de votre compte.
• completeBy est la date limite, au format ISO 8601. Sans elle, le candidat dispose de sept jours.
• message est un mot que le candidat lit dans l’invitation, jusqu’à 1 000 caractères.
• language vaut en, es, fr ou pt, et en par défaut. C’est la langue de l’e-mail d’invitation quand le candidat est contacté par e-mail.

Un champ que la route ne connaît pas reçoit un 400, comme pour toutes les écritures de cette API.

{
  "screening": {
    "screeningId": "8d3f6a2e-4b1c-4f0a-9e7d-2c5b8a1f0e3d",
    "jobId": "job_01J8Z3K9Q0EXAMPLE",
    "candidateId": "app_01J9B2C3D4EXAMPLE",
    "templateId": "tpl_01J9C3D4E5EXAMPLE",
    "status": "invited",
    "deliveryPath": "token",
    "completeBy": "2026-10-02T00:00:00.000Z",
    "requestedAt": "2026-09-25T01:10:00.000Z"
  },
  "billing": "overage",
  "priceCents": 300,
  "currency": "AUD"
}

• deliveryPath indique comment le candidat a été contacté, de la même manière qu’Orbit le fait : interview est une demande d’entretien sur son CV Virtuel, et token un e-mail avec un lien à usage unique. Son adresse e-mail n’est jamais renvoyée.
• billing vaut included quand la présélection a utilisé l’une de celles incluses dans l’offre, et overage quand c’est une présélection supplémentaire.
• priceCents est le prix par présélection du modèle, figé à cet instant, en unités mineures et hors GST. Une présélection supplémentaire n’est facturée à ce prix que si le candidat la termine : s’il ne la passe jamais, elle ne coûte rien.

D’où viennent les identifiants

• jobId est l’id que le poste a reçu à sa création, ou celui que GET /v1/jobs renvoie à une clé qui lit les offres.
• L’identifiant du candidat est celui qu’Orbit utilise pour lui sur ce poste. C’est la dernière partie de l’adresse de sa page dans Orbit : …/jobs/{jobId}/candidates/{candidateId}.

Une présélection à la fois

Un candidat a une présélection par poste à la fois. Tant qu’une présélection est ouverte, une deuxième requête est refusée, et le refus porte la présélection ouverte dans error.screening, pour que votre système reprenne celle-ci au lieu d’envoyer une autre invitation.

Cela rend aussi sûre une nouvelle tentative après un délai dépassé. Si la première requête est passée, la nouvelle tentative est refusée avec la présélection qu’elle a créée, et le candidat n’est invité qu’une fois.

Quand elle est refusée

Une requête refusée n’envoie rien et ne laisse rien de réservé.

Un 429 ici concerne le candidat, pas votre clé : réessayer plus tôt n’y change rien. La route n’est pas soumise à la limite de requêtes par minute et n’envoie pas d’en-têtes X-RateLimit-* : ce qui la borne, c’est une présélection ouverte par candidat et par poste, et la limite mensuelle des présélections supplémentaires.

Référence