> ## 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`).
**L'API n'est pas encore ouverte.** `api.spottracker.fr` n'est pas déployé à
ce jour : le bouton **Try it** de cette page ne peut joindre aucun serveur et
répondra `An error occurred while making the request: no response received`.
Les exemples de requête et de réponse ci-dessous sont générés depuis le code
du back et décrivent fidèlement ce que l'API renverra — ils restent la
référence en attendant l'ouverture.
Les comptes prioritaires, avec le signal qui les a fait remonter et l'action recommandée.
Chaque appel porte votre clé dans l'en-tête `Authorization`, schéma `Bearer`.
## 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 publique
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'
'400':
description: >-
Paramètre de pagination invalide : `limit` hors bornes, `offset`
négatif, `since` non parsable, ou paramètre inconnu. `message` porte
alors une entrée par contrainte non respectée.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
statusCode: 400
message:
- limit must not be greater than 200
error: BAD_REQUEST
path: /v1/leads?limit=999
timestamp: '2026-08-25T14:32:07.412Z'
'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.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
statusCode: 401
message: Clé d’API invalide.
error: UNAUTHORIZED
path: /v1/me
timestamp: '2026-08-25T14:32:07.412Z'
'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.
headers:
Retry-After:
description: Secondes à attendre avant la prochaine fenêtre.
schema:
type: integer
example: 37
X-RateLimit-Limit:
description: Requêtes autorisées par fenêtre d’une minute.
schema:
type: integer
example: 120
X-RateLimit-Remaining:
description: Requêtes restantes dans la fenêtre en cours.
schema:
type: integer
example: 0
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorDto'
example:
statusCode: 429
message: Limite de 120 requêtes par minute atteinte.
error: TOO_MANY_REQUESTS
path: /v1/companies
timestamp: '2026-08-25T14:32:07.412Z'
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
ApiErrorDto:
type: object
properties:
statusCode:
type: number
description: >-
Code HTTP, répété dans le corps pour les clients qui ne lisent que
le JSON.
example: 401
message:
description: >-
Message lisible. C'est un tableau lorsque l'erreur vient de la
validation
des paramètres (un message par contrainte non respectée).
oneOf:
- type: string
- type: array
items:
type: string
example: Clé d’API invalide.
error:
type: string
description: >-
Nom symbolique du statut HTTP, en majuscules (`UNAUTHORIZED`,
`NOT_FOUND`…).
example: UNAUTHORIZED
path:
type: string
description: Chemin appelé, en-têtes de requête exclus.
example: /v1/me
timestamp:
type: string
description: Date de l'erreur, ISO 8601 en UTC.
format: date-time
example: '2026-08-25T14:32:07.412Z'
required:
- statusCode
- message
- error
- path
- timestamp
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.
````