Ressources

Organization


1. Présentation de la ressource

Il s’agit d’une ressource qui regroupe les données décrivant la « structure » :

  • numéros SIREN/ SIRET ou FINESS, type de structure (géographique ou juridique), activité , secteur d’activité santé, catégorie juridique, modalités de participation au service public hospitalier (SPH),
  • raison sociale, enseigne commerciale, coordonnées (adresse postale, adresses de messagerie électronique, téléphones),


2. Caractéristiques techniques de la ressource

Endpoint

https://gateway.api.esante.gouv.fr/fhir/v2/Organization

Header

ESANTE-API-KEY

Méthodes HTTP associées

GET, POST

Paramètres de requête

_count, _include, _revinclude

3. Paramètres de recherche (Search Parameter)

Nom Type Description
_id token Recherche sur l’ID technique de la ressource Organization
_lastUpdated date renvoie uniquement les ressources selon la date de mises à jour et le “modifier” utilisé (eq, ne, gt, lt, ge, le, ap). Plus d’informations sur les [dates] (hhttps://www.hl7.org/fhir/R4/search.html#date)
active token Recherche selon le statut de l’organisation
address string Recherche sur le champ adresse de l’organisation
address-city string Recherche sur la commune de l’organisation
address-postalcode string Recherche sur le code postal de l’organisation
data-information-system token Recherche sur le système d’information
identifier token Recherche sur l’identifiant de la structure
identifier-type token Recherche sur le type d’identifiant de la structure
mailbox-mss string Recherche sur les messageries sécurisées de santé (MSS) rattachées aux organisations
name string Recherche sur la raison sociale des structures
partof reference Recherche tous les établissements géographiques rattachés à une même entité juridique
pharmacy-licence string Recherche sur le numéro de licence des pharmacies officines
type token Recherche sur le type de structure/ code APE/ catégorie juridique/ secteur d’activité/ catégorie d’établissement ou le code SPH de la structure

4. Recherche de structure sur critères

Voici quelques exemples de requêtes sur les structures.

4.1 Rechercher tout (sans critère)

Récit utilisateur : En tant que client de l’API, je souhaite récupérer l’ensemble des structures.

Requêtes :

GET [base]/Organization
# récupère l'ensemble des structures (incluant les actives et les inactives)

GET [base]/Organization?_include=Organization:partof 
# récupère les entités géographiques ainsi que leurs entités juridiques associées

GET [base]/Organization?_revinclude=Device:organization 
# récupère les entités ainsi que leurs équipements matériels lourds associés

GET [base]/Organization?_revinclude=HealthcareService:organization 
# récupère les entités ainsi que leurs activités de soins associés

GET [base]/Organization?_revinclude=PractitionerRole:organization 
# récupère les entités ainsi que toutes les activités des professionnels associées

GET [base]/Organization?_include=* 
# inclure toutes les ressources qui sont référencées par les Organization (Device, PractitionerRole, HealthCareService)


Exemples de code:

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" https://gateway.api.esante.gouv.fr/fhir/v2/Organization
// Création du client
var client = FhirTestUtils.createClient();
var bundle = client.search().forResource(Organization.class).returnBundle(Bundle.class).execute();
for(var organizationEntry : bundle.getEntry()){
// print les IDs des organisations
    var organization = (Organization) organizationEntry.getResource();
    logger.info("Organization found: id={} name={}", organization.getIdElement().getIdPart(), organization.getName());
}
// Création du client
var client = FhirTestUtils.CreateClient();

var bundle = client.Search<Organization>();
foreach (var be in bundle.Entry)
{
    // print les IDs:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: id={organization.IdElement.Value} name={organization.Name}");
}


4.2 Rechercher par raison sociale (name)

Récit utilisateur : En tant que client de l’API, je souhaite trouver une structure à partir de sa raison sociale.

Requête :

GET [base]/Organization?name:contains=imagerie,centre
# récupère les structures dont la raison sociale contient imagerie ou centre. Cette recherche n'est pas sensible à la casse.


Exemples de code:

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v2/Organization?name%3Acontains=imagerie%2Ccentre"
// Création du client
var client = FhirTestUtils.createClient();

// Création du Search Parameter name
var nameSearchClause = Organization.NAME.contains().values("imagerie", "centre");

var bundle = client.search()
.forResource(Organization.class)
.where(nameSearchClause)
.returnBundle(Bundle.class).execute();

for(var organizationEntry : bundle.getEntry()){

// Convertir l'entrée
var organization = (Organization) organizationEntry.getResource();

// print data :
logger.info("Organization found: name={}", organization.getName());
}
// Création du client
var client = FhirTestUtils.CreateClient();

var q = new SearchParams()
  .Where("name:contains=imagerie").Add("name:contains", "centre")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
// Print IDs
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: name={organization.Name}");
}


4.3 Rechercher par identifiant structure (identifier)

Récit utilisateur : En tant que client de l’API, je souhaite rechercher une structure à partir de son identifiant structure

Requête :

GET [base]/Organization?identifier=001604103000
# récupérer une structure dont l'identifiant de structure est 001604103000

GET [base]/Organization?identifier=https%3A%2F%2Ffiness.esante.gouv.fr%7C590064036
# récupérer une structure appartenant au référentiel FINESS et dont l'identifiant de structure est 590064036 


Exemples de code:

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v2/Organization?identifier=001604103000"
// create the client:
var client = FhirTestUtils.createClient();

// create the identifier search parameter :
var idParam = new StringClientParam("identifier");

var bundle = client.search()
.forResource(Organization.class)
.where(idParam.matches().values("001604103000"))
.returnBundle(Bundle.class).execute();

for(var organizationEntry : bundle.getEntry()){
// cast entry :
var organization = (Organization) organizationEntry.getResource();
// print update date & id :
logger.info("Organization found: id={}", organization.getIdentifierFirstRep().getValue());
}
// create the client:
var client = FhirTestUtils.CreateClient();

var q = new SearchParams()
  .Where("identifier=001604103000")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // print ids:
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: id={organization.IdElement.Value}");
}


4.4 Rechercher par date de mise à jour (_lastUpdated)

Récit utilisateur : En tant que client de l’API, je souhaite rechercher toutes les structures mises à jour depuis une certaine date.

Requête :

GET [base]/Organization?_lastUpdated=ge2025-08-05
# Récupère toutes les structures mises à jour à partir du 05 août 2025 (inclus) jusqu'à aujourd'hui


Exemples de code:

curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v2/Organization?_lastUpdated=ge2025-08-05T14%3A51%3A04"
var client = FhirTestUtils.createClient();

// Création du paramètre de recherche Date
var dateParam = new DateClientParam("_lastUpdated");

var bundle = client.search()
        .forResource(Organization.class)
        .where(dateParam.afterOrEquals().second("2025-08-05T14:51:04"))
        .returnBundle(Bundle.class).execute();

for(var organizationEntry : bundle.getEntry()){
    // cast entry :
    var organization = (Organization) organizationEntry.getResource();
    // print update date & id :
    logger.info("Organization found: id={} lastUpdate={}", organization.getIdElement().getIdPart(), organization.getMeta().getLastUpdated());
}
// Création du client
var client = FhirTestUtils.CreateClient();

var q = new SearchParams()
  .Where("_lastUpdated=ge2025-08-05T14:51:04")
  .LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
    // Print les IDs
    var organization = be.Resource as Organization;
    Console.WriteLine($"Organization found: id={organization.IdElement.Value} lastUpdate={organization.Meta.LastUpdated}");
}


4.5 Rechercher par type (type)

Le champs “Type” de la ressource Organization peut contenir des informations différentes en fonction du code système renseigné. Le type permet de rechercher sur le secteur d’activité, la catégorie d’établissement, le type d’organisation (entité géographique, entité juridique), etc.

Type de données Code système
Type d’organisation https://hl7.fr/ig/fhir/core/2.1.0/ValueSet-fr-core-vs-organization-type.html
APE/NAF https://mos.esante.gouv.fr/NOS/TRE_R75-InseeNAFrev2Niveau5/FHIR/TRE-R75-InseeNAFrev2Niveau5
Catégorie Juridique https://mos.esante.gouv.fr/NOS/TRE_R72-FinessStatutJuridique/FHIR/TRE-R72-FinessStatutJuridique
Secteur d’activité https://mos.esante.gouv.fr/NOS/TRE_R02-SecteurActivite/FHIR/TRE-R02-SecteurActivite
Catégorie d’établissement https://mos.esante.gouv.fr/NOS/TRE_R66-CategorieEtablissement/FHIR/TRE-R66-CategorieEtablissement
SPH https://mos.esante.gouv.fr/NOS/TRE_R73-ESPIC/FHIR/TRE-R73-ESPIC

Lorsque vous souhaitez rechercher sur un type de données particulier, utiliser les combinaisons suivantes :

  • Renseigner le code système concerné
  • Renseigner le code fonctionnel de la valeur souhaité


Exemples de requêtes :

GET [base]/Organization?type=https://mos.esante.gouv.fr/NOS/TRE_R66-CategorieEtablissement/FHIR/TRE-R66-CategorieEtablissement%7C101
# récupère les organisations qui appartiennent à la catégorie d'établissement 101 - Centre Hospitalier Régional (C.H.R.) en indiquant la TRE

GET [base]/Organization?type=GEOGRAPHICAL-ENTITY
# récupère les organisations qui sont uniquement des entités géographiques.

GET [base]/Organization?type=LEGAL-ENTITY
# récupère les organisations qui sont uniquement des entités juridiques.

GET [base]/Organization?type=https://mos.esante.gouv.fr/NOS/TRE_R02-SecteurActivite/FHIR/TRE-R02-SecteurActivite%7CSA02
# récupère les organisations qui font partie du secteur d'activité SA02 en indiquant la TRE


4.6 Rechercher par code postal et ville (address-postalcode et address-city)

Récit utilisateur : En tant que client de l’API, je souhaite rechercher les structures d’un département (code postal).

Requêtes :

GET [base]/Organization?address-postalcode=75016&address-city=PARIS
# récupère les organisations qui sont dans la commune de Paris et qui ont un code postal 75016

GET [base]/Organization?address-postalcode=78
# récupère les organisations qui sont dans le département des Yvelines (78)


Exemples de code:

 curl -H "ESANTE-API-KEY: XXXX-XXXX-XXXX-XXXXX" "https://gateway.api.esante.gouv.fr/fhir/v2/Organization?address-postalcode=75016&address-city=PARIS" 
 
// create the client: 
var client = FhirTestUtils.createClient();

// create the search parameters:
var postalCodeParam = Organization.ADDRESS_POSTALCODE.matchesExactly().values("75016");
var cityParam = Organization.ADDRESS_CITY.matchesExactly().values("PARIS");

var bundle = client.search()
.forResource(Organization.class)
.where(postalCodeParam)
.and(cityParam)
.returnBundle(Bundle.class).execute();

for (var organizationEntry : bundle.getEntry()) {

// Convertir l'entrée:
var organization = (Organization) organizationEntry.getResource();
// print la data:
logger.info("Organization found: name={} | zipCode={} | city={}",
organization.getName(),
organization.getAddressFirstRep().getPostalCode(),
organization.getAddressFirstRep().getCity());
}
 import requests from fhir.resources.fhirtypes import Bundle, Organization

# Configuration du client
api_url = "https://gateway.api.esante.gouv.fr/fhir/v2/Organization"
api_key = "XXXX-XXXX-XXXX-XXXXX"
postal_code = "75016"
city = "PARIS"

headers = {
"ESANTE-API-KEY": api_key,
"Content-Type": "application/json"
}

# Fonction pour effectuer une requête FHIR avec un code postal et une ville
def fetch_organizations_by_postal_code_and_city():
response = requests.get(f"{api_url}?address-postalcode={postal_code}&address-city={city}", headers=headers)
if response.status_code == 200:
bundle = Bundle(**response.json())
for entry in bundle.entry:
organization = entry.resource
if isinstance(organization, Organization):
name = organization.name if organization.name else "Unknown"
zip_code = organization.address[0].postalCode if organization.address else "Unknown"
city_name = organization.address[0].city if organization.address else "Unknown"
print(f"Organization found: name={name} | zipCode={zip_code} | city={city_name}")
else:
response.raise_for_status()

 # Utilisation du client
fetch_organizations_by_postal_code_and_city()
 

// create the client: 
var client = FhirTestUtils.CreateClient();
var q = new SearchParams()
.Where("address-postalcode=75016")
.And("address-city=PARIS")
.LimitTo(50);
var bundle = client.Search<Organization>(q);
foreach (var be in bundle.Entry)
{
// print ids:
var organization = be.Resource as Organization;
Console.WriteLine($"Organization found: name={organization.Name} | zipCode={organization.Address[0].PostalCode} | city={organization.Address[0].City}");
}


4.7 Rechercher par source d’informations

Récit utilisateur : En tant que client de l’API, je souhaite rechercher les structures par rapport à la source d’informations de la donnée

Requête :

GET [base]/Organization?data-information-system=RPPS
# récupère les organisations qui proviennent de la source d'information RPPS

GET [base]/Organization?data-information-system=FINESS
# récupère les organisations qui proviennent de la source d'information FINESS


Code source des exemples

Vous retrouverez le code source de ces exemples sur notre repository git: