Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Insourcia Events API
description: 'API publique Insourcia pour la recherche et l''analyse de sociétés françaises. ## Authentification
Chaque requête porte un en-tête `Authorization: Bearer `. Deux types de jetons sont acceptés :
- **Clé API** (format `isk_xxx`) : à créer dans l''application, rubrique Paramètres > API / MCP (`https://app.insourcia.io/settings/api`) ;
- **JWT OAuth 2.1** : obtenu par le parcours OAuth du serveur MCP. ## Facturation en crédits
L''API se paie sur le solde de crédits de votre organisation. **1 crédit = 1 fiche société.** Chaque opération indique son coût en tête de description (« Coût : ») et dans l''extension `x-credits`, lisible par un programme : `base` (crédits par appel), `perResult` (par résultat de recherche servi), `sections` (crédits par société servie, pour chaque section non vide), `subscriptionOnly` (opération réservée aux abonnements), `freeRelookup` (relecture gratuite, pendant `freeRelookupDays` jours, soit 30). **Règles de facturation.**
- Seul ce qui est servi est facturé : une section vide ne coûte rien, une société introuvable ne coûte rien. - Une erreur est gratuite : seule une réponse 2xx est débitée. Un 4xx ou un 5xx (paramètre invalide, refus, `server_busy`) ne débite rien. - Relire la même section d''une même société dans les 30 jours qui suivent son premier débit est gratuit, entre la fiche, ses sections et leurs lots (par exemple `GET /companies/{siren}/financials` puis `GET /companies/batch/financials`). Une recherche est facturée à chaque appel. - Avant l''appel, le coût maximal est réservé sur le solde ; après, seul le coût réel est débité et le reste est rendu. Un appel dont le coût maximal dépasse le solde est refusé (402) sans rien débiter. - Les sections réservées aux abonnements (score crédit, estimation financière, email de dirigeant, données Insourcia d''une recherche) sont omises d''une réponse sans abonnement et listées dans `_billing.sections_skipped`, sans coût. Une opération entièrement réservée répond 403 `subscription_required`. **Coût et solde dans chaque réponse facturable.**
- `X-Credits-Charged` : crédits débités par cet appel (0 pour une relecture ou un rejeu). - `X-Credits-Remaining` : solde de l''organisation après l''appel. - `X-Credits-Grant-Remaining` et `X-Credits-Grant-Expires-At` : reste et date d''expiration des crédits offerts du mois. - `X-Billing-Grid-Version` : version de la grille qui a calculé le coût. - Le bloc `_billing` du corps (`charged`, `breakdown`, `free_relookups`, `sections_skipped`, `grid_version`) détaille le calcul. Il est ajouté sur demande, avec `?billing=1` ou l''en-tête `X-Billing-Detail: 1`. - `GET /me` donne le solde à tout moment (bloc `credits`), gratuitement. **Rejeu sans double débit.** Un en-tête `Idempotency-Key` (200 caractères au plus) lie l''appel à ses arguments pendant 24 h : le même appel renvoyé sous la même clé est servi à nouveau sans être débité. La même clé sur un autre appel répond 409 `idempotency_key_reused`, et sur un appel encore en cours 409 `idempotency_key_in_progress`. **Erreurs de facturation.**
- 402 `insufficient_credits` : solde insuffisant pour le coût maximal de l''appel (`credits_remaining`, `credits_required`). - 402 `spend_cap_reached` : plafond de dépense quotidien ou mensuel de l''organisation atteint (`cap` : `daily` ou `monthly`). - 403 `subscription_required` : opération réservée aux abonnements. - 409 `idempotency_key_reused` / `idempotency_key_in_progress` : voir ci-dessus. - 503 `service_unavailable` : facturation momentanément indisponible, rien n''est débité. **Offre.** 100 crédits offerts chaque mois à toute organisation, dès l''inscription. Recharge à 0,01 € le crédit, sans expiration. Abonnements :
| Abonnement | Crédits inclus |
|---|---|
| 49 € par mois | 10 000 crédits par mois |
| 99 € par mois | 20 000 crédits par mois |
| 199 € par mois | 40 000 crédits par mois |
| 499 € par mois | 100 000 crédits par mois |
| 999 € par mois | 200 000 crédits par mois |
Grille `2026-11-12.v9` (en-tête `X-Billing-Grid-Version`).'
version: 1.0.0
x-billing-grid-version: 2026-11-12.v9
contact:
name: Insourcia Support
email: support@insourcia.io
servers:
- url: https://api.insourcia.io/v1
description: Production
security:
- bearerAuth: []
tags:
- name: Events
description: Chronologie des événements d'une société (annonces BODACC, dépôts de comptes, marchés publics, changements de dirigeants)
paths:
/events/search:
get:
x-credits:
credits: 0.1
unit: par résultat
note: 0,1 crédit par résultat servi.
subscribers: false
perResult: 0.1
subscriptionOnly: false
freeRelookup: false
tags:
- Events
summary: Recherche unifiée d'événements (multi-SIREN)
description: '**Coût :** 0,1 crédit par résultat servi.
Renvoie des événements individuels `{ date, type, siren, denomination, data }`, sur plusieurs
sociétés à la fois : cessions, procédures collectives, dépôts de comptes, augmentations de
capital, marchés publics, subventions, radiations et créations.
Requiert au moins un filtre `region` / `departement` / `ville` / `code_naf`, ou un filtre
d''événement (`date_min`, `date_max`, `cedant_siren`, `cessionnaire_siren`,
`prix_min`/`prix_max`, `tribunal`, `procedure_type`), sinon 400 `missing_prefilter`.
Pagination par curseur, ouverte à tous les comptes ; 1 000 événements au plus par recherche.'
operationId: searchEvents
parameters:
- name: type
in: query
description: 'Types (CSV) : cession, procedure, depot_comptes, augmentation_capital, marche_public, subvention, radiation, creation. Par défaut : tous. Les types issus du flux de veille (dirigeant_*, changement_*) ne sont pas disponibles sur cette recherche multi-SIREN.'
schema:
type: string
- name: date_min
in: query
schema:
type: string
format: date
- name: date_max
in: query
schema:
type: string
format: date
- name: cedant_siren
in: query
schema:
type: string
- name: cessionnaire_siren
in: query
schema:
type: string
- name: prix_min
in: query
schema:
type: number
- name: prix_max
in: query
schema:
type: number
- name: tribunal
in: query
schema:
type: string
- name: procedure_type
in: query
description: 'Type(s) de procédure (CSV) : liquidation, redressement, sauvegarde, conciliation'
schema:
type: string
- name: region
in: query
schema:
type: string
- name: departement
in: query
schema:
type: string
- name: ville
in: query
description: 'Nom de ville. Plusieurs villes séparées par virgule. Ex : Paris,Lyon'
schema:
type: string
- name: code_naf
in: query
schema:
type: string
- name: limit
in: query
description: 'Nombre d''événements par page. Maximum : 20 ; une valeur supérieure est ramenée à 20 et signalée dans `warnings`.'
schema:
type: integer
default: 20
minimum: 1
maximum: 20
- name: cursor
in: query
description: 'Curseur de pagination. 1 000 événements au plus par recherche : au-delà, 400 `search_depth_exceeded`.'
schema:
type: string
responses:
'402':
$ref: '#/components/responses/CreditsRequired'
'200':
description: Flux d'événements
content:
application/json:
schema:
$ref: '#/components/schemas/EventSearch'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
/companies/{siren}/events:
get:
x-credits:
credits: 0.5
unit: par société
note: 'Par société servie et par section non vide : événements 0,5. Relire une même société et section dans les 30 jours est gratuit.'
subscribers: false
sections:
events: 0.5
subscriptionOnly: false
freeRelookup: true
freeRelookupDays: 30
tags:
- Events
summary: Timeline d'événements d'une société
description: '**Coût :** Par société servie et par section non vide : événements 0,5. Relire une même société et section dans les 30 jours est gratuit.
Flux chronologique décroissant pour un SIREN unique, réunissant deux
sources :
- les **agrégats** (cessions[], procédures[], dates scalaires) :
historique complet, dates juridiques ;
- le **flux de veille** : détection plus précoce, et
seule source des mouvements de dirigeants (`dirigeant_entry` /
`dirigeant_exit` / `dirigeant_change`), des changements de note
(`changement_note`) et des changements SIRENE de siège et d''activité
(`modification_administrative`, libellé explicite).
Un même fait publié au BODACC peut apparaître dans les deux sources. Il est
alors servi une seule fois, sous sa forme agrégée (date juridique, `data`
structuré), enrichie de `data.source_url` et `data.date_effet` quand seul le
flux de veille les porte.
Le rapprochement se fait sur l''identifiant de l''annonce BODACC quand les
deux sources le portent. Les avis distincts ne sont jamais fusionnés, et un
rectificatif tardif n''est jamais compté deux fois. Sans identifiant commun,
il se fait par proximité de date.
`data.source_url` est aussi fourni sur les événements `cession` et
`procedure` issus des agrégats : il couvre donc tout l''historique.
Une indisponibilité du flux de veille dégrade la réponse aux seuls agrégats,
sans erreur. Pagination par `offset`.'
operationId: getEvents
parameters:
- $ref: '#/components/parameters/siren'
- name: type
in: query
description: Filtrer par type(s) d'événement (CSV)
schema:
type: string
- name: date_min
in: query
schema:
type: string
format: date
- name: date_max
in: query
schema:
type: string
format: date
- name: limit
in: query
schema:
type: integer
default: 50
minimum: 1
maximum: 200
- name: offset
in: query
schema:
type: integer
default: 0
responses:
'402':
$ref: '#/components/responses/CreditsRequired'
'200':
description: Timeline de la société
content:
application/json:
schema:
$ref: '#/components/schemas/EventTimeline'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
components:
parameters:
siren:
name: siren
in: path
required: true
description: 'SIREN à 9 chiffres, avec une clé de contrôle (Luhn) valide. Un numéro qui
échoue la clé reçoit 400 `invalid_siren` ; un SIREN valide sans société
reçoit 404 `not_found`. Seule exception à la clé : La Poste (356000000).
'
schema:
type: string
pattern: ^\d{9}$
example: '380129866'
responses:
RateLimited:
description: Limite de débit atteinte (fenêtre glissante d'une minute). Rien n'est débité.
headers:
Retry-After:
schema:
type: integer
description: Secondes avant de pouvoir réessayer
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Error'
- type: object
properties:
window:
type: string
enum:
- minute
retry_after_seconds:
type: integer
limit_source:
type: string
enum:
- user
- organization
description: '`organization` quand la limite est celle de l''organisation (clé d''organisation), `user` sinon.'
example:
error: rate_limited
window: minute
retry_after_seconds: 12
limit_source: organization
message: Trop de requetes (plafond 25/minute). Reessayez dans 12 s.
BadRequest:
description: Paramètres invalides
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: invalid_parameter
message: The 'q' parameter is required.
message_fr: Le paramètre 'q' est requis.
Unauthorized:
description: Clé API invalide ou manquante
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
message: Invalid or missing API key.
message_fr: Clé API invalide ou manquante.
NotFound:
description: Société introuvable
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: not_found
message: No company found for SIREN 000000000.
message_fr: Aucune entreprise trouvée pour le SIREN 000000000.
CreditsRequired:
description: 'Facturation en crédits uniquement. Solde de crédits insuffisant pour le coût maximal de l''appel
(`insufficient_credits`), ou plafond de dépense de l''organisation atteint (`spend_cap_reached`).
Rien n''est débité.
'
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- insufficient_credits
- spend_cap_reached
message:
type: string
credits_remaining:
type: number
description: Solde de l'organisation (`insufficient_credits`).
credits_required:
type: number
description: Coût maximal réservé pour cet appel (`insufficient_credits`).
cap:
type: string
enum:
- daily
- monthly
description: Plafond atteint (`spend_cap_reached`).
example:
error: insufficient_credits
message: Solde de crédits insuffisant pour cet appel.
credits_remaining: 0.4
credits_required: 1
schemas:
EventSearch:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Event'
pagination:
type: object
properties:
limit:
type: integer
has_more:
type: boolean
next_cursor:
type: string
EventTimeline:
type: object
properties:
siren:
type: string
denomination:
type: string
data:
type: array
items:
$ref: '#/components/schemas/Event'
pagination:
type: object
properties:
total:
type: integer
limit:
type: integer
offset:
type: integer
has_more:
type: boolean
Event:
type: object
description: 'Événement unifié. Deux sources sont réconciliées : l''historique des
publications légales (dates juridiques) et le flux de veille (date de
détection). `/events/search` sert les types `cession`, `procedure`,
`depot_comptes`, `augmentation_capital`, `marche_public`, `subvention`,
`radiation` et `creation` ; les autres types ne sont servis que par
`/companies/{siren}/events`.
'
properties:
date:
type: string
format: date
description: 'Date juridique pour un événement issu des agrégats ; jour de
DÉTECTION pour un événement issu du flux de veille (`data.detecte_le`).
Voir `data.date_effet` pour la date d''effet quand elle est connue.
'
type:
type: string
enum:
- cession
- procedure
- depot_comptes
- augmentation_capital
- marche_public
- subvention
- radiation
- creation
- immatriculation
- dirigeant_entry
- dirigeant_exit
- dirigeant_change
- changement_denomination
- changement_note
- modification_administrative
siren:
type: string
description: Présent uniquement dans /events/search (multi-SIREN).
denomination:
type: string
description: Présent uniquement dans /events/search.
data:
type: object
additionalProperties: true
description: Champs spécifiques au type d'événement.
Error:
type: object
properties:
error:
type: string
description: Code d'erreur stable. C'est lui qu'un client doit lire pour réagir, jamais le texte de `message`.
message:
type: string
description: Explication pour un développeur ou un agent, en anglais.
message_fr:
type: string
description: Version française de `message`, pour l'afficher telle quelle à un utilisateur francophone. Absente quand `message` n'a pas de version française.
parameter:
type: string
description: 'Sur un `invalid_parameter` qui refuse des valeurs inconnues : le paramètre en cause (ex. `fields`).'
unknown:
type: array
items:
type: string
description: Les valeurs refusées par ce paramètre, telles qu'envoyées. Présent avec `parameter`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Clé API (isk_xxx) ou JWT OAuth 2.1