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

# Search Executives

Look up executives (dirigeants) for one or more companies. Provide SIREN numbers directly, or supply company search filters to resolve them automatically. You must provide either `siren_numbers` or `filters` + `limit` — not both.

## Request Body

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="siren_numbers" type="string[]">
      List of SIREN numbers to look up executives for.
    </ParamField>

    <ParamField body="filters" type="object">
      Company search filters. Used with `limit` to first search companies, then fetch their executives. All filter fields are optional.

      <Expandable title="filter fields">
        <ParamField body="q" type="string[]">
          Free-text search terms (e.g. company name).
        </ParamField>

        <ParamField body="activite_principale" type="string[]">
          NAF/APE activity codes (e.g. `["62.01Z", "62.02A"]`).
        </ParamField>

        <ParamField body="etat_administratif" type="string">
          Administrative status. `"A"` for active, `"C"` for closed.
        </ParamField>

        <ParamField body="tranche_effectif_salarie" type="string[]">
          Employee count ranges. Allowed values: `"0"`, `"1-9"`, `"10-49"`, `"50-199"`, `"200-499"`, `"500+"`.
        </ParamField>

        <ParamField body="departement" type="string[]">
          French department codes (e.g. `["75", "92", "93"]`).
        </ParamField>

        <ParamField body="region" type="string">
          French region code (e.g. `"11"` for Ile-de-France).
        </ParamField>

        <ParamField body="code_postal" type="string[]">
          Postal codes (e.g. `["75001", "75002"]`).
        </ParamField>

        <ParamField body="nature_juridique" type="string[]">
          Legal form categories. Allowed values: `"Entreprises individuelles"`, `"Sociétés commerciales"`, `"Sociétés civiles"`, `"Associations"`, `"Autres"`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="limit" type="integer">
      Maximum number of companies to search when using `filters`.
    </ParamField>

    <ParamField body="role_types" type="string[]">
      Filter executives by role. Accepts **role group names** or individual Pappers role labels (or a mix of both).

      **Role groups** (recommended for UI filters):

      * `"Executives"` — Président, Directeur général, DGD, Gérant, PCA, Membre du directoire, Chef d'entreprise
      * `"Governance & Audit"` — Administrateur, Membre du conseil de surveillance, Commissaire aux comptes (titulaire + suppléant)
      * `"Shareholders & Other"` — Membre, Associé indéfiniment responsable, Autre
      * `"Liquidator"` — Liquidateur
      * `"All"` — no filtering (returns every role)

      **Individual role labels** (for fine-grained control):
      `"Président"`, `"Directeur général"`, `"Directeur général délégué"`, `"Gérant"`,
      `"Gérant et associé indéfiniment responsable"`, `"Président du conseil d'administration"`,
      `"Membre du directoire"`, `"Chef d'entreprise"`,
      `"Administrateur"`, `"Membre du conseil de surveillance"`,
      `"Commissaire aux comptes titulaire"`, `"Commissaire aux comptes suppléant"`,
      `"Membre"`, `"Associé indéfiniment responsable"`, `"Autre"`,
      `"Liquidateur"`

      If omitted, all roles are returned.
    </ParamField>

    <ParamField body="status_filter" type="string">
      Filter by executive status. `"current"` for active executives, `"former"` for former executives, `"all"` or omit for both.
    </ParamField>

    <ParamField body="page" type="integer" default="1">
      Page number for paginated results. Each page returns up to 20 executives. Defaults to `1`.
    </ParamField>
  </Expandable>
</ParamField>

## Credit Cost

**1 credit per company/SIREN** queried. Credits are charged on the full result set on the first page request — subsequent pages for the same query cost nothing extra.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://search.leads-siren.com/enrichment-service/search_executives \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "siren_numbers": ["123456789", "987654321"],
        "role_types": ["Président", "Directeur général", "Gérant"],
        "status_filter": "current",
        "page": 1
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://search.leads-siren.com/enrichment-service/search_executives",
      headers={"x-api-key": "YOUR_API_KEY"},
      json={
          "data": {
              "siren_numbers": ["123456789", "987654321"],
              "role_types": ["Président", "Directeur général", "Gérant"],
              "status_filter": "current",
              "page": 1
          }
      }
  )
  print(resp.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "total": 36,
    "page": 1,
    "per_page": 20,
    "total_pages": 2,
    "people": [
      {
        "nom_complet": "Jean Dupont",
        "qualite": "Président",
        "status": "current",
        "date_de_naissance": "1975-03-15",
        "entreprises": [ ... ]
      }
    ]
  }
  ```

  ```json 402 theme={null}
  {
    "detail": "Insufficient credits (have 2, need 5)"
  }
  ```
</ResponseExample>