# searchTransparenceSanteBeneficiaries

**Identifier:** `transparencesante_searchTransparenceSanteBeneficiaries`

**Provider:** [TransparenceSante](https://kirha.com/providers/transparencesante.md)

Search beneficiaries of the French Transparence Santé database (health professionals, hospitals, learned societies, associations...) and rank them by amount received. Find a person by name or RPPS, or map KOLs: top beneficiaries of a company (by SIREN or name), filtered by year, link type, profession, city or department. Returns beneficiaryIds and RPPS numbers for getTransparenceSanteBeneficiaryLinks. Agreement amounts can overlap the remunerations paid under them, so compare link types separately.

## Run it with the CLI

```bash
kirha tools run transparencesante_searchTransparenceSanteBeneficiaries \
  --input '{}'
```

`--input` takes a JSON object that matches the input schema. Pass `--input -` to read it from stdin.

## Call it over HTTP

```bash
curl https://api.kirha.com/tools/v1/execute \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: **********' \
  --data '{
  "tool_name": "transparencesante_searchTransparenceSanteBeneficiaries",
  "input": {}
}'
```

Replace the stars with an API key from https://app.kirha.com/api-keys.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "beneficiaryCategory": {
      "enum": [
        "health_professional",
        "healthcare_facility",
        "health_professional_association",
        "academy_foundation_learned_society",
        "patient_association",
        "student",
        "student_association",
        "initial_or_continuing_training_body",
        "press_media",
        "influencer",
        "software_publisher",
        "veterinarian",
        "veterinary_company",
        "health_grouping",
        "agricultural_grouping"
      ],
      "type": "string"
    },
    "city": {
      "minLength": 2,
      "type": "string"
    },
    "companyName": {
      "description": "Full-text match on the declaring company name",
      "minLength": 2,
      "type": "string"
    },
    "companySiren": {
      "description": "9-digit SIREN of the declaring company",
      "pattern": "^\\d{9}$",
      "type": "string"
    },
    "departmentCode": {
      "description": "e.g. 75, 69, 2A, 974",
      "maxLength": 3,
      "minLength": 2,
      "type": "string"
    },
    "firstName": {
      "description": "Prefix match",
      "minLength": 1,
      "type": "string"
    },
    "lastName": {
      "minLength": 2,
      "type": "string"
    },
    "limit": {
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    },
    "linkType": {
      "enum": [
        "benefit",
        "agreement",
        "remuneration"
      ],
      "type": "string"
    },
    "profession": {
      "description": "e.g. Médecin, Infirmier, Pharmacien",
      "minLength": 3,
      "type": "string"
    },
    "rpps": {
      "description": "11-digit RPPS number",
      "pattern": "^\\d{11}$",
      "type": "string"
    },
    "year": {
      "description": "Declaration year",
      "maximum": 2100,
      "minimum": 2012,
      "type": "integer"
    }
  },
  "type": "object"
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "properties": {
    "beneficiaries": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "agreementsAmount": {
            "type": "number"
          },
          "beneficiaryId": {
            "description": "Transparence Santé beneficiary ID",
            "type": "string"
          },
          "benefitsAmount": {
            "type": "number"
          },
          "category": {
            "type": "string"
          },
          "cities": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "declarations": {
            "type": "number"
          },
          "fullName": {
            "type": "string"
          },
          "identifier": {
            "type": "string"
          },
          "identifierType": {
            "description": "ADELI, SIREN, FINESS, RNA, ORDRE...",
            "type": "string"
          },
          "profession": {
            "type": "string"
          },
          "remunerationsAmount": {
            "type": "number"
          },
          "rpps": {
            "type": "string"
          },
          "totalAmount": {
            "type": "number"
          }
        },
        "required": [
          "beneficiaryId",
          "declarations",
          "benefitsAmount",
          "remunerationsAmount",
          "agreementsAmount",
          "totalAmount"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "beneficiaryIds": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "context": {
      "type": "string"
    },
    "currency": {
      "const": "eur",
      "type": "string"
    },
    "rppsNumbers": {
      "items": {
        "type": "string"
      },
      "type": "array"
    }
  },
  "required": [
    "context",
    "currency",
    "beneficiaries",
    "beneficiaryIds",
    "rppsNumbers"
  ],
  "type": "object"
}
```

## Related tools

Other TransparenceSante tools that this tool refers to, or that refer to it.

- [`getTransparenceSanteBeneficiaryLinks`](https://kirha.com/providers/transparencesante/getTransparenceSanteBeneficiaryLinks.md)
- [`searchTransparenceSanteCompanies`](https://kirha.com/providers/transparencesante/searchTransparenceSanteCompanies.md)

-----

[All TransparenceSante tools](https://kirha.com/providers/transparencesante.md) · [< Back to tools list](https://kirha.com/tools.md)