Basile Suggestions API

openapi: 3.2.0
info:
  title: Basile Suggestions API
  version: 1.0.0
  description: '**Basile** est une base de données B2B française : ~26,8 M sociétés et ~29,5 M

    contacts, issus du croisement de trois sources :

    - **Legal** — registre légal français (INSEE / INPI-RNE) : dirigeants, SIREN, NAF, forme juridique…

    - **LKI** — profils LinkedIn : intitulé de poste, séniorité, compétences, écoles…

    - **GMB** — Google My Business : note, avis, horaires, catégorie…


    L''API expose deux recherches symétriques — **personnes** (`/people`) et

    **entreprises** (`/companies`) — avec un système de filtres `include`/`exclude`,

    un comptage gratuit avant extraction, et un export CSV enrichi.


    ### Authentification

    Toutes les requêtes portent la clé API dans le header `Authorization`, **en clair,

    sans préfixe `Bearer`** : `Authorization: REDACTED_STRIPE_KEY`.


    ### `find` vs `export` : ce que chacun renvoie

    Les deux acceptent exactement les mêmes `filters`. La différence est la **richesse des données**.


    - **`/people/find` renvoie la personne, PAS sa société.** Identité, localisation, poste,

    URL LinkedIn, plus le **nom** et l''**identifiant interne** de son employeur — mais **aucune**

    donnée de cette société : ni SIREN/NAF/forme juridique, ni effectif/secteur/description,

    ni note/avis/adresse Google.

    - **`/people/export` renvoie la ligne complète : 92 colonnes** — 22 sur la personne,

    **18 sur sa société LinkedIn**, **31 sur sa société au registre légal**, **11 Google Maps**,

    6 drapeaux de présence. Pour UNE fiche, `GET /people/{id}/full` rend le même modèle sans

    passer par un export.

    - **`/companies/find` croise DÉJÀ les trois sources** : chaque résultat porte sa fiche et,

    quand la correspondance existe, celles des deux autres sources sous `x_legal` / `x_lki` /

    `x_gmb`. Contrairement aux personnes, inutile d''exporter pour voir les trois sources.

    - **`/companies/export` renvoie 70 colonnes** : les mêmes données mises à plat en CSV.


    Règle pratique : pour des contacts avec le contexte de leur entreprise, `/find` sert à cibler

    et à compter, puis **c''est `/export` qui produit la donnée exploitable**.


    ### Facturation

    **Compter est gratuit, sans limite.** Envoyez `{ "countOnly": true }` (ou `limit: 0`) :

    la réponse contient `total` et un tableau `leads` vide, et **rien n''est débité**.


    **Récupérer des enregistrements coûte 1 crédit par enregistrement renvoyé** — sur `/find`

    (hors mode count-only), sur `/people/{id}` et `/companies/{id}`, et sur `/export`. Le débit

    a lieu **à chaque appel** : redemander les mêmes enregistrements est **re-facturé** (la

    donnée a pu être rafraîchie depuis ; il n''existe pas de registre « déjà payé »).


    ⚠️ `limit: 1` n''est **pas** un mode de comptage : il renvoie 1 enregistrement, donc

    1 crédit. Pour compter, utilisez `countOnly: true`.


    Quota épuisé → **402** `quota_exhausted`, renvoyé **avant** les enregistrements : rien

    n''est livré et rien n''est débité.


    Règle d''or : **comptez d''abord** avec `countOnly`, puis n''extrayez que les enregistrements

    dont vous avez besoin.'
  contact:
    name: Support Basile
    url: https://basile.cc
    email: contact@basile.cc
servers:
- url: https://api.basile.cc
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Suggestions
  description: Autocomplétion pour trouver les valeurs valides des filtres.
paths:
  /people/roles/suggest:
    get:
      tags:
      - Suggestions
      summary: Suggérer des intitulés de poste
      operationId: suggestRoles
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Liste de suggestions.
  /people/cities/suggest:
    get:
      tags:
      - Suggestions
      summary: Suggérer des villes (personnes)
      operationId: suggestPeopleCities
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Liste de villes.
  /companies/activity-suggest:
    get:
      tags:
      - Suggestions
      summary: Suggérer des activités (concepts pour le filtre `activity`)
      description: Renvoie des IDs de concept (taxonomie unifiée NAF · Maps · LinkedIn) à passer dans `filters.activity`.
      operationId: suggestActivity
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Concepts correspondants.
  /companies/legal-form-suggest:
    get:
      tags:
      - Suggestions
      summary: Suggérer des formes juridiques
      operationId: suggestLegalForms
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Formes juridiques.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Clé API en clair (sans `Bearer`). Ex : `Authorization: sk_live_xxxx`.'