> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicehire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Lister les candidats

> Récupère la liste des candidats d'une campagne avec leur synthèse d'entretien

## Paramètres

<ParamField path="campaign_id" type="string" required>
  Identifiant unique de la campagne
</ParamField>

<ParamField query="page" type="integer" default="1">
  Numéro de la page à récupérer
</ParamField>

<ParamField query="per_page" type="integer" default="50">
  Nombre de résultats par page (maximum: 100)
</ParamField>

<ParamField query="sort" type="string" default="date_desc">
  Ordre de tri des résultats

  Valeurs possibles:

  * `date_desc` - Plus récents en premier
  * `date_asc` - Plus anciens en premier
  * `score_desc` - Meilleurs scores en premier
  * `score_asc` - Scores les plus faibles en premier
</ParamField>

<ParamField query="filter_status" type="string">
  Filtrer par statut d'entretien

  Valeurs possibles:

  * `completed` - Entretiens terminés
  * `voicemail` - Tombés sur répondeur
  * `pending` - En attente d'appel
</ParamField>

## Réponse

<ResponseExample>
  ```json theme={null}
  {
    "candidates": [
      {
        "candidate_id": "550e8400-e29b-41d4-a716-446655440000",
        "first_name": "Jean",
        "last_name": "Dupont",
        "email": "jean.dupont@example.com",
        "phone": "0612345678",
        "status": "completed",
        "interview_score": 8.5,
        "interview_date": "2024-01-15T14:30:00Z",
        "availability": "Immédiatement",
        "salary_expectation": "45000-50000€",
        "candidate_alignment": "Excellente correspondance avec le profil recherché",
        "strengths": "Expérience solide en React, Bonne communication, Motivé",
        "concerns": "Peu d'expérience en gestion d'équipe",
        "is_sourced": false
      }
    ],
    "pagination": {
      "total": 125,
      "page": 1,
      "per_page": 50,
      "total_pages": 3
    }
  }
  ```
</ResponseExample>

<ResponseField name="candidates" type="array" required>
  Liste des candidats

  <Expandable title="Propriétés de chaque candidat">
    <ResponseField name="candidate_id" type="string" required>
      Identifiant unique du candidat (UUID)
    </ResponseField>

    <ResponseField name="first_name" type="string" required>
      Prénom du candidat
    </ResponseField>

    <ResponseField name="last_name" type="string" required>
      Nom de famille du candidat
    </ResponseField>

    <ResponseField name="email" type="string" required>
      Email du candidat
    </ResponseField>

    <ResponseField name="phone" type="string" required>
      Numéro de téléphone
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Statut de l'entretien (`completed`, `voicemail`, `pending`, `incomplete`)
    </ResponseField>

    <ResponseField name="interview_score" type="number">
      Score de l'entretien (0-10), null si non complété
    </ResponseField>

    <ResponseField name="interview_date" type="string">
      Date de l'entretien (ISO 8601)
    </ResponseField>

    <ResponseField name="availability" type="string">
      Disponibilité du candidat
    </ResponseField>

    <ResponseField name="salary_expectation" type="string">
      Prétentions salariales
    </ResponseField>

    <ResponseField name="candidate_alignment" type="string">
      Analyse de l'alignement avec le poste
    </ResponseField>

    <ResponseField name="strengths" type="string">
      Points forts identifiés
    </ResponseField>

    <ResponseField name="concerns" type="string">
      Points d'attention
    </ResponseField>

    <ResponseField name="is_sourced" type="boolean" required>
      Indique si le candidat a été sourcé via SMS
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Informations de pagination

  <Expandable title="Propriétés">
    <ResponseField name="total" type="integer" required>
      Nombre total de candidats
    </ResponseField>

    <ResponseField name="page" type="integer" required>
      Page actuelle
    </ResponseField>

    <ResponseField name="per_page" type="integer" required>
      Nombre de résultats par page
    </ResponseField>

    <ResponseField name="total_pages" type="integer" required>
      Nombre total de pages
    </ResponseField>
  </Expandable>
</ResponseField>

## Exemple de requête

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.voicehire.io/api/v1/campaigns/abc123def456/candidates?sort=score_desc" \
    -H "X-API-Key: vh_live_XXXXXXXXXXXXX"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.voicehire.io/api/v1/campaigns/abc123def456/candidates",
      headers={
          "X-API-Key": "vh_live_XXXXXXXXXXXXX"
      },
      params={
          "sort": "score_desc"
      }
  )
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.get(
    'https://app.voicehire.io/api/v1/campaigns/abc123def456/candidates',
    {
      headers: {
        'X-API-Key': 'vh_live_XXXXXXXXXXXXX'
      },
      params: {
        sort: 'score_desc'
      }
    }
  );
  ```
</CodeGroup>

## Codes d'erreur

| Code | Description                     |
| ---- | ------------------------------- |
| 400  | Paramètres de requête invalides |
| 401  | Clé API manquante ou invalide   |
| 404  | Campagne non trouvée            |


## OpenAPI

````yaml GET /api/v1/campaigns/{campaign_id}/candidates
openapi: 3.0.3
info:
  title: VoiceHire API
  description: >
    API REST pour automatiser les campagnes de recrutement avec VoiceHire.


    ## Authentification


    L'API utilise une authentification par clé API. Vous devez inclure votre clé
    API dans l'en-tête `X-API-Key` de chaque requête.


    ```

    X-API-Key: vh_live_XXXXXXXXXXXXX

    ```


    ## Format des réponses


    Toutes les réponses sont au format JSON. Les erreurs suivent un format
    standardisé :


    ```json

    {
      "error": {
        "code": "ERROR_CODE",
        "message": "Description de l'erreur",
        "details": {}
      }
    }

    ```


    ## Limites


    - Les numéros de téléphone doivent être des numéros français (06 ou 07)

    - Maximum 100 candidats par requête d'ajout

    - Les campagnes génèrent automatiquement 6 questions d'entretien
  version: 1.0.0
  contact:
    name: Support VoiceHire
    email: support@voicehire.io
    url: https://www.voicehire.io
servers:
  - url: https://app.voicehire.io
    description: Production
  - url: http://localhost:8080
    description: Développement local
security:
  - ApiKeyAuth: []
tags:
  - name: Campagnes
    description: Gestion des campagnes de recrutement
  - name: Candidats
    description: Gestion des candidats
  - name: Compte
    description: Informations du compte
paths:
  /api/v1/campaigns/{campaign_id}/candidates:
    get:
      tags:
        - Candidats
      summary: Lister les candidats d'une campagne
      description: Récupère la liste des candidats avec options de filtrage et tri
      operationId: listCandidates
      parameters:
        - name: campaign_id
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: status
          in: query
          description: Filtrer par statut
          schema:
            type: string
            enum:
              - completed
              - pending
              - voicemail
        - name: min_score
          in: query
          description: Score minimum
          schema:
            type: number
            minimum: 0
            maximum: 10
        - name: sort
          in: query
          description: Ordre de tri
          schema:
            type: string
            enum:
              - date_desc
              - date_asc
              - score_desc
              - score_asc
            default: date_desc
      responses:
        '200':
          description: Liste des candidats
          content:
            application/json:
              schema:
                type: object
                properties:
                  candidates:
                    type: array
                    items:
                      $ref: '#/components/schemas/CandidateSummary'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
                      total_pages:
                        type: integer
components:
  schemas:
    CandidateSummary:
      type: object
      properties:
        id:
          type: integer
          description: ID du candidat
        uuid:
          type: string
          description: UUID du candidat
        first_name:
          type: string
        last_name:
          type: string
        phone_number:
          type: string
        email:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - completed
            - pending
            - voicemail
            - incomplete
        interview_score:
          type: number
          nullable: true
          description: Score de l'entretien (sur 10)
        date:
          type: string
          format: date-time
        is_sourced:
          type: boolean
          description: Candidat sourcé (avec SMS)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clé API au format vh_live_XXXXX

````