> ## 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 campagnes

> Récupère la liste de toutes les campagnes de votre structure avec pagination

## Paramètres de requête

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

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

<ParamField query="status" type="string">
  Filtrer les campagnes par statut

  Valeurs possibles:

  * `active` - Campagnes actives
  * `paused` - Campagnes en pause
  * `completed` - Campagnes terminées
</ParamField>

## Réponse

<ResponseExample>
  ```json theme={null}
  {
    "campaigns": [
      {
        "campaign_id": "abc123def456",
        "job_title": "Développeur Full Stack",
        "status": "active",
        "total_candidates": 25,
        "created_at": "2024-01-15T10:30:00Z"
      },
      {
        "campaign_id": "ghi789jkl012",
        "job_title": "Commercial B2B",
        "status": "completed",
        "total_candidates": 50,
        "created_at": "2024-01-10T14:20:00Z"
      }
    ],
    "total": 15,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
  ```
</ResponseExample>

<ResponseField name="campaigns" type="array">
  Liste des campagnes

  <Expandable title="Propriétés">
    <ResponseField name="campaign_id" type="string" required>
      Identifiant unique de la campagne
    </ResponseField>

    <ResponseField name="job_title" type="string" required>
      Titre du poste pour cette campagne
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Statut actuel de la campagne (`active`, `paused`, `completed`)
    </ResponseField>

    <ResponseField name="total_candidates" type="integer" required>
      Nombre total de candidats dans la campagne
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      Date de création de la campagne (format ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required>
  Nombre total de campagnes correspondant aux critères
</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>

## Codes d'erreur

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


## OpenAPI

````yaml GET /api/v1/campaigns
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:
    get:
      tags:
        - Campagnes
      summary: Lister les campagnes
      description: Récupère la liste de toutes les campagnes de l'agence
      operationId: listCampaigns
      parameters:
        - name: page
          in: query
          description: Numéro de page (commence à 1)
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: Nombre d'éléments par page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          description: Filtrer par statut
          schema:
            type: string
            enum:
              - active
              - paused
              - completed
      responses:
        '200':
          description: Liste des campagnes
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
                  page:
                    type: integer
                  per_page:
                    type: integer
                  total:
                    type: integer
                  total_pages:
                    type: integer
              example:
                campaigns:
                  - campaign_id: CAMP-20250701-ABC123
                    job_title: Développeur Full Stack
                    client_name: TechCorp
                    status: active
                    created_at: '2025-07-01T10:00:00Z'
                    candidate_count: 15
                    candidate_link: https://app.voicehire.io/apply/CAMP-20250701-ABC123
                page: 1
                per_page: 20
                total: 1
                total_pages: 1
        '401':
          description: Non authentifié
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Campaign:
      type: object
      properties:
        campaign_id:
          type: string
          description: Identifiant unique de la campagne
          example: CAMP-20250701-ABC123
        job_title:
          type: string
          description: Titre du poste
          example: Développeur Full Stack
        client_name:
          type: string
          description: Nom de l'entreprise cliente
          example: TechCorp SAS
        status:
          type: string
          enum:
            - active
            - paused
            - completed
          description: Statut de la campagne
        created_at:
          type: string
          format: date-time
          description: Date de création
        candidate_count:
          type: integer
          description: Nombre de candidats
          example: 25
        candidate_link:
          type: string
          format: uri
          description: Lien pour les candidats
          example: https://app.voicehire.io/apply/CAMP-20250701-ABC123
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Code d'erreur machine-readable
              example: MISSING_API_KEY
            message:
              type: string
              description: Message d'erreur human-readable
              example: API key is required
            details:
              type: object
              description: Détails supplémentaires sur l'erreur
              additionalProperties: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clé API au format vh_live_XXXXX

````