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

# Lister les leads

> Triés par score d’intention décroissant. `since` filtre sur la date de création du lead (`createdAt`).



## OpenAPI

````yaml /openapi.json get /v1/leads
openapi: 3.0.0
info:
  title: API publique SpotTracker
  description: >-
    API de lecture des entreprises identifiées sur votre site, de leurs contacts
    et des leads qualifiés. Incluse à partir de l'offre Growth.
  version: '1'
  contact: {}
servers:
  - url: https://api.spottracker.fr
    description: Production
security: []
tags: []
paths:
  /v1/leads:
    get:
      tags:
        - api-v1
      summary: Lister les leads
      description: >-
        Triés par score d’intention décroissant. `since` filtre sur la date de
        création du lead (`createdAt`).
      operationId: listLeads
      parameters:
        - name: limit
          required: false
          in: query
          schema:
            minimum: 1
            maximum: 200
            default: 50
            type: number
        - name: offset
          required: false
          in: query
          schema:
            minimum: 0
            default: 0
            type: number
        - name: since
          required: false
          in: query
          schema:
            format: date-time
            example: '2026-08-01T00:00:00Z'
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicLeadPageDto'
        '401':
          description: >-
            Clé absente, invalide, révoquée, offre insuffisante ou workspace
            suspendu. Ces cas répondent à l’identique, volontairement :
            distinguer les motifs renseignerait un attaquant qui balaye des
            clés.
        '429':
          description: >-
            Limite de débit atteinte pour cette clé. L’en-tête `Retry-After`
            indique le nombre de secondes avant la prochaine fenêtre.
      security:
        - apiKey: []
components:
  schemas:
    PublicLeadPageDto:
      type: object
      properties:
        total:
          type: number
          description: >-
            Nombre total d'éléments correspondant au filtre, toutes pages
            confondues.
          example: 137
        limit:
          type: number
          description: Taille de page effectivement appliquée.
          example: 50
        offset:
          type: number
          example: 0
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicLeadDto'
      required:
        - total
        - limit
        - offset
        - data
    PublicLeadDto:
      type: object
      properties:
        id:
          type: string
        companyId:
          type: string
          description: Entreprise d'origine — utilisable sur `GET /v1/companies/{id}`.
        companyName:
          type: string
          example: Atelier Vermeil
        contactName:
          type: string
          example: Camille Perrin
        contactTitle:
          type: string
          example: Directrice des opérations
        contactEmail:
          type: string
          nullable: true
          description: Renseigné quand le visiteur s'est identifié.
        intentScore:
          type: number
          minimum: 0
          maximum: 100
          example: 82
        intentLevel:
          allOf:
            - $ref: '#/components/schemas/IntentLevel'
        signal:
          type: string
          description: Signal ayant déclenché la remontée, en clair.
          example: 3 visites sur la page Tarifs en 48 heures
        recommendedAction:
          type: string
          example: Appeler sous 24 heures
        status:
          allOf:
            - $ref: '#/components/schemas/CrmStatus'
        assignedToId:
          type: string
          nullable: true
          description: Membre du workspace assigné. `null` si le lead n'est pas attribué.
        createdAt:
          format: date-time
          type: string
      required:
        - id
        - companyId
        - companyName
        - contactName
        - contactTitle
        - intentScore
        - intentLevel
        - signal
        - recommendedAction
        - status
        - createdAt
    IntentLevel:
      type: string
      enum:
        - hot
        - warm
        - cold
    CrmStatus:
      type: string
      enum:
        - new
        - qualified
        - in_crm
        - contacted
        - won
        - lost
  securitySchemes:
    apiKey:
      scheme: bearer
      type: http
      description: >-
        Clé d'API du workspace, préfixée `st_`. Elle se crée depuis
        Administration → Tracking et n’est affichée qu’une seule fois.

````