API REST · v1

Documentation API

Accédez par programmation aux données officielles des entreprises françaises.

Introduction

L’API Pôle Sociétés est une API REST qui renvoie du JSON. Toutes les requêtes se font en HTTPS sur l’URL de base ci-dessous. Chaque appel doit être authentifié avec une clé API.

URL de base

https://api.polesocietes.com/api/v1

Authentification

L’authentification se fait par clé API (préfixe ps_live_). Transmettez-la dans l’en-tête Authorization en Bearer, ou via l’en-tête X-API-Key. La clé n’est affichée qu’une seule fois à sa création : conservez-la en lieu sûr et ne l’exposez jamais côté client.

En-tête (recommandé)

Authorization: Bearer ps_live_VOTRE_CLE

Alternative

X-API-Key: ps_live_VOTRE_CLE

Pas encore de clé ? Choisissez une offre et obtenez votre clé.

Quotas & limites de débit

Chaque offre inclut un quota mensuel d’appels et une limite de débit par minute. Les réponses exposent l’état de votre quota dans les en-têtes suivants :

En-tête	Description
X-Quota-Limit	Quota mensuel d’appels de votre offre.
X-Quota-Remaining	Appels restants sur la période en cours.
X-Quota-Reset	Horodatage Unix de la remise à zéro du quota.

Une fois le quota mensuel atteint, l’API répond 429 avec l’erreur quota_exceeded jusqu’au renouvellement. Les appels terminant en erreur (4xx/5xx) ne sont pas décomptés de votre quota.

Exemple d’en-têtes de réponse

HTTP/1.1 200 OK
X-Quota-Limit: 5000
X-Quota-Remaining: 4997
X-Quota-Reset: 1783522570

Codes d’erreur

Les erreurs renvoient un code HTTP standard et un corps JSON { "error": "…", "message": "…" }.

HTTP	error	Description
401	unauthenticated	Clé API manquante, invalide, révoquée ou expirée.
402	subscription_required	Aucun abonnement API actif rattaché à la clé.
403	forbidden	La clé ne dispose pas de la portée (scope) requise par l’endpoint.
404	financials_not_found	Aucune donnée financière disponible pour cette entreprise.
422	—	Paramètres de requête invalides (le détail est dans le corps).
429	quota_exceeded	Quota mensuel d’appels atteint. Voir le champ reset_at.
429	rate_limited	Trop de requêtes en peu de temps (limite par minute).

GET/api/v1/companies/searchscope : search

Recherche d’entreprises

Recherche des entreprises françaises par raison sociale, SIREN ou SIRET, avec filtres optionnels. Les résultats sont paginés.

Paramètres

Nom	Type	Requis	Description
q	string	Oui	Terme de recherche : raison sociale, SIREN ou SIRET.
activity_code	string	Non	Filtre sur le code APE/NAF (ex. 6201Z).
department	string	Non	Filtre sur le département (ex. 75).
state	string	Non	État de l’entreprise (active, cessée…).
page	integer	Non	Numéro de page (défaut : 1).
per_page	integer	Non	Résultats par page (1 à 100, défaut : 50).

Exemple de requête

curl "https://api.polesocietes.com/api/v1/companies/search?q=la%20poste" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ps_live_VOTRE_CLE"

Exemple de réponse

{
  "data": [
    {
      "siren": "356000000",
      "siret": "35600000000048",
      "name": "LA POSTE",
      "active_since": "1991-01-01",
      "state": "active",
      "legal_form": {
        "code": "5710",
        "label": "Société par actions simplifiée (SAS)",
        "short": "SAS"
      },
      "ape_code": {
        "code": "53.10Z",
        "label": "Activités de poste dans le cadre d’une obligation de service universel"
      },
      "employees": 150000,
      "share_capital": null,
      "vat_number": "FR39356000000",
      "rcs_number": "356 000 000 RCS PARIS",
      "address": "9 RUE DU COLONEL PIERRE AVIA, 75015 PARIS",
      "location": "PARIS",
      "is_kbis_available": true
    }
  ],
  "links": { "first": "…", "last": "…", "prev": null, "next": "…" },
  "meta": { "current_page": 1, "per_page": 50, "total": 124 }
}

GET/api/v1/companies/{siren}/financialsscope : financials

Données financières

Chiffres clés et ratios financiers par exercice (chiffre d’affaires, résultat, EBITDA, marges, délais de paiement…) pour une entreprise, à partir de son SIREN. Répond 404 si aucune donnée n’est disponible.

Paramètres

Nom	Type	Requis	Description
siren	string	Oui	SIREN à 9 chiffres, dans l’URL.

Exemple de requête

curl "https://api.polesocietes.com/api/v1/companies/356000000/financials" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ps_live_VOTRE_CLE"

Exemple de réponse

{
  "data": {
    "siren": "356000000",
    "years": [
      {
        "year": "2023",
        "turnover": 34073000000,
        "profit": 1287000000,
        "EBITDA": 2456000000,
        "gross_margin": 41.2,
        "operating_margin": 7.2,
        "financial_autonomy": 32.5,
        "solvency": 48.1,
        "liquidity": 1.4,
        "client_payment_delay": 38,
        "supplier_payment_delay": 52,
        "total_assets": 51200000000
      }
    ]
  }
}

Tarifs

Choisissez l’offre adaptée à votre volume d’appels. Le quota se renouvelle chaque mois.

Offre	Appels	Prix
Starter	5 000 / mois	29,90 € / mois
Growth	15 000 / mois	69 € / mois
Scale	50 000 / mois	149,90 € / mois
Enterprise	50 000+ / mois	Sur devis

Voir les offres & obtenir une clé