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

# Utiliser l'Expansion API

> Authentifiez-vous, effectuez vos premiers appels à l'Expansion API, paginez les résultats et lisez les scores d'expansion.

<Info>
  Ce guide de démarrage rapide vous amène de zéro à la lecture de signaux d'expansion en direct en quelques appels. Il suppose que vous disposez déjà d'une clé API Pubrio — voir [Authentification](/fr/api-reference/authentication) pour en créer une.
</Info>

## Prérequis

* Une clé API Pubrio (voir [Authentification](/fr/api-reference/authentication)).
* Le `domain_search_id` d'une entreprise. Vous pouvez en obtenir un via le point de terminaison [Company Search](/fr/api-reference/endpoint/companies/search).

Tous les points de terminaison Expansion sont en `POST` et acceptent un corps JSON. Incluez vos identifiants sur chaque requête comme décrit dans [Authentification](/fr/api-reference/authentication).

## Étape 1 — Consulter l'expansion d'une entreprise

Commencez par une seule entreprise et listez chaque marché sur lequel elle s'étend.

```bash theme={null}
POST /expansions/companies/lookup
{ "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "is_all_markets": true }
```

```json theme={null}
{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "home_country_code": "US" },
  "data": { "market_count": 2, "dominant_stage_slug": "expanding", "total_signal_count": 194 },
  "markets_summary": [
    { "country_code": "GB", "stage_slug": "expanding", "is_home_market": false, "signal_count": 140, "distinct_type_count": 6, "latest_signal_at": "2026-07-08T02:42:23.544Z", "rank_now": 1 },
    { "country_code": "DE", "stage_slug": "committing", "is_home_market": false, "signal_count": 54, "distinct_type_count": 3, "latest_signal_at": "2026-06-20T00:00:00.000Z", "rank_now": 2 }
  ]
}
```

## Étape 2 — Lire le résultat

Chaque entrée de `markets_summary` décrit un marché sur lequel l'entreprise est active :

* **`stage_slug`** — jusqu'où l'entreprise a progressé sur ce marché (`exploring` → `scaling`).
* **`signal_count`** / **`distinct_type_count`** — combien de preuves étayent le marché, sur combien de types de signaux.
* **`latest_signal_at`** — l'ancienneté du signal le plus récent.
* **`signal_velocity_30d`** / **`signal_velocity_90d`** — la vitesse à laquelle l'activité s'accélère.
* **`rank_now`** — le rang actuel du marché pour cette entreprise (`1` = le plus fort).
* **`is_home_market`** — s'il s'agit du pays du siège de l'entreprise.

Pour faire ressortir les mouvements les plus récents ou filtrer par trajectoire, utilisez les points de terminaison de découverte (`freshness`, `momentum`) présentés ensuite.

## Étape 3 — Explorer un marché entier

Pour travailler par marché plutôt que par entreprise, utilisez [Expansion Market Detail](/fr/api-reference/endpoint/expansions/market_lookup). Il est paginé avec les paramètres standards `page` / `per_page`.

La géographie est une relation orientée **de → vers**, exprimée par deux listes : `froms` (marchés d'origine / siège) et `tos` (marchés cibles). Choisissez le motif correspondant à votre question :

<CodeGroup>
  ```bash Entrant (vers GB) theme={null}
  POST /expansions/search
  {
    "tos": ["GB"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash Sortant (depuis CN) theme={null}
  POST /expansions/search
  {
    "froms": ["CN"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash Corridor (CN → GB) theme={null}
  POST /expansions/search
  {
    "froms": ["CN"],
    "tos": ["GB"],
    "page": 1,
    "per_page": 25
  }
  ```
</CodeGroup>

Lisez `metadata.pagination` pour parcourir les résultats page par page :

```json theme={null}
{
  "metadata": {
    "filters": { "tos": ["GB"], "freshness": ["fresh", "cooling"] }
  },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 64, "total_pages": 3 },
    "companies": [ /* ... */ ]
  }
}
```

Demandez la page suivante en incrémentant `page`. `per_page` est plafonné selon votre plan — demander explicitement plus que votre plafond renvoie une erreur plutôt que de tronquer silencieusement.

Deux valeurs par défaut à connaître :

* **Ordre** — les résultats reviennent dans l'ordre de pertinence (entreprises corroborées par plusieurs types de signaux en premier, puis les plus récentes). Passez `sort_by: "recent"` pour une pure récence, ou `expansion_score` / `signal_count` / `company_ranking`.
* **Réponses allégées** — les réponses par clé API omettent par défaut l'agrégat de marché (`metadata.aggregate`, principales origines/destinations, chronologie) et le détail du modèle. Passez `is_include_metadata: true` pour les obtenir.

## Étape 4 — Explorer les preuves en détail

Lorsque vous voulez les signaux individuels derrière le mouvement d'une entreprise, appelez [Company Signal Events](/fr/api-reference/endpoint/expansions/company_pulse_events).

```bash theme={null}
POST /expansions/companies/pulse_events
{
  "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
  "signal_types": ["HIRE", "EXEC", "NEWS"],
  "window_days": 90,
  "page": 1
}
```

Ce point de terminaison renvoie `total_entries` et `total_pages` — demandez les pages `1` à `total_pages` (c'est-à-dire continuez tant que `page` \< `total_pages`).

## Référence de filtrage

La plupart des points de terminaison Expansion acceptent ces filtres. Leurs valeurs valides sont listées dans [How Expansion Signals Work](/fr/knowledge-base/concepts/how-expansion-signals-work) :

| Filtre         | Objectif                                                                             |
| -------------- | ------------------------------------------------------------------------------------ |
| `stages`       | Limiter à une ou plusieurs étapes d'expansion.                                       |
| `freshness`    | Limiter par ancienneté des preuves.                                                  |
| `momentum`     | Limiter par trajectoire (`advancing`/`steady`/`pulling_back`).                       |
| `scopes`       | Limiter par portée d'entrée sur le marché.                                           |
| `signal_types` | Limiter à des types de signaux spécifiques.                                          |
| `froms`        | Marchés d'origine / siège (expansion **depuis**).                                    |
| `tos`          | Marchés cibles (expansion **vers**).                                                 |
| `companies`    | Cibler des entreprises spécifiques par `domain_search_id`, domaine, ou URL LinkedIn. |

Le filtre `companies` accepte n'importe quel mélange de types d'identifiants — pas besoin de les résoudre en identifiants au préalable :

<CodeGroup>
  ```bash Par domaine theme={null}
  POST /expansions/search
  { "companies": ["stripe.com", "airbnb.com"] }
  ```

  ```bash Par URL LinkedIn theme={null}
  POST /expansions/search
  { "companies": ["https://www.linkedin.com/company/stripe"] }
  ```

  ```bash Par domain_search_id theme={null}
  POST /expansions/search
  { "companies": ["550e8400-e29b-41d4-a716-446655440002"] }
  ```
</CodeGroup>

<Warning>
  Ne confondez pas **flux** et **trajectoire**. Le flux (la direction du mouvement entre marchés) est défini par `froms` / `tos` — il n'existe pas de filtre de requête `direction`. La trajectoire (comment le mouvement progresse) est le filtre `momentum`, et elle apparaît dans les réponses sous le champ `direction`.
</Warning>

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Exemple concret" href="/fr/knowledge-base/concepts/expansion-signals-example">
    Le parcours complet du marché au signal.
  </Card>

  <Card title="Points de terminaison Expansion" href="/fr/api-reference/endpoint/expansions/dashboard">
    Parcourez tous les points de terminaison de l'Expansion API.
  </Card>
</CardGroup>