Skip to main content
POST
/
api
/
v1
/
campaigns
/
{campaign_id}
/
candidates
Ajouter des candidats
curl --request POST \
  --url https://app.voicehire.io/api/v1/campaigns/{campaign_id}/candidates \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "candidates": [
    {
      "first_name": "Jean",
      "last_name": "Dupont",
      "phone_number": "+33612345678",
      "email": "jean.dupont@example.com"
    },
    {
      "first_name": "Marie",
      "last_name": "Martin",
      "phone_number": "+33687654321"
    }
  ]
}
'
{
  "campaign_id": "abc123def456",
  "candidates_added": 23,
  "candidates_skipped": 2,
  "calls_queued": 23,
  "errors": [
    {
      "index": 5,
      "error": "Numéro de téléphone invalide"
    }
  ]
}

​
Paramètres

​
campaign_id
string
required
Identifiant unique de la campagne

​
Corps de la requête

​
contact_mode
string
default:"call"
Méthode de contact :
  • call (défaut) — Appel téléphonique automatique immédiat. email requis pour chaque candidat.
  • sms — SMS d’invitation à passer l’entretien, avec lien personnalisé (0,25 crédit). Le candidat clique et lance lui-même l’entretien quand il le souhaite. Failover email : si le phone est absent ou invalide mais qu’un email valide est fourni, l’invitation part par email (gratuit).
  • email — Email d’invitation à passer l’entretien, avec lien personnalisé (gratuit). Failover SMS : si l’email est absent ou invalide mais qu’un phone valide est fourni, l’invitation part par SMS (0,25 crédit).
Pour sms et email, chaque candidat doit fournir au moins une coordonnée valide (phone ou email), sinon il est rejeté.
​
candidates
array
required
Liste des candidats à ajouter (maximum 100)

​
Réponse

{
  "campaign_id": "abc123def456",
  "candidates_added": 23,
  "candidates_skipped": 2,
  "calls_queued": 23,
  "errors": [
    {
      "index": 5,
      "error": "Numéro de téléphone invalide"
    }
  ]
}
L’exemple ci-dessus correspond au mode call. En modes sms et email, la réponse a la forme : candidates_sourced, candidates_skipped, sms_sent, emails_sent, errors.
​
campaign_id
string
required
Identifiant de la campagne
​
candidates_added
integer
required
Nombre de candidats ajoutés avec succès
​
candidates_skipped
integer
required
Nombre de candidats ignorés (déjà présents dans la campagne)
​
calls_queued
integer
required
Nombre d’appels mis en file d’attente
​
errors
array
Liste des erreurs rencontrées

​
Exemple de requête

curl -X POST https://app.voicehire.io/api/v1/campaigns/abc123def456/candidates \
  -H "X-API-Key: vh_live_XXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "candidates": [
      {
        "first_name": "Jean",
        "last_name": "Dupont",
        "phone": "0612345678",
        "email": "jean.dupont@example.com"
      },
      {
        "first_name": "Marie",
        "last_name": "Martin",
        "phone": "0687654321",
        "email": "marie.martin@example.com"
      }
    ]
  }'

​
Notes importantes

  • Les candidats déjà présents dans la campagne (même téléphone ou même email) sont ignorés (skipped)
  • Maximum 100 candidats par requête
  • En modes sms et email, un failover s’applique par candidat : si le canal principal n’a pas de coordonnée valide, l’autre canal est utilisé s’il est disponible. Le coût facturé correspond au canal réellement utilisé.
  • Le coût en crédits dépend du canal effectivement utilisé :
Canal utiliséActionCoût par candidat traité avec succès
call (défaut)Appel téléphonique automatique immédiat1 crédit (transaction_type = campaign)
smsSMS d’invitation avec lien personnalisé0,25 crédit (transaction_type = sourcing)
emailEmail d’invitation avec lien personnaliséGratuit
Aucun crédit n’est débité pour les candidats skippés (doublon), ni en cas d’échec d’envoi.

​
Codes d’erreur

CodeDescription
400Données invalides (format incorrect, champs manquants)
401Clé API manquante ou invalide
402Crédits insuffisants
404Campagne non trouvée

Authorizations

​
X-API-Key
string
header
required

Clé API au format vh_live_XXXXX

Path Parameters

​
campaign_id
string
required

Identifiant de la campagne

Body

application/json
​
candidates
object[]
required
Required array length: 1 - 100 elements
​
contact_mode
enum<string>
default:call

Méthode de contact :

  • call (défaut) : appel téléphonique automatique immédiat. email requis par candidat.
  • sms : SMS d'invitation à passer l'entretien (0,25 crédit). Failover email : si le phone est absent/invalide mais qu'un email valide est fourni, l'invitation part par email (gratuit).
  • email : email d'invitation à passer l'entretien (gratuit). Failover SMS : si l'email est absent/invalide mais qu'un phone valide est fourni, l'invitation part par SMS (0,25 crédit).

Pour sms et email, chaque candidat doit fournir au moins une coordonnée valide (phone OU email), sinon il est rejeté.

Available options:
call,
sms,
email

Response

Candidats ajoutés avec succès

​
added
integer

Nombre de candidats ajoutés

​
duplicates
integer

Nombre de doublons ignorés

​
invalid
integer

Nombre de candidats invalides

​
calls_queued
integer

Nombre d'appels en file d'attente