API documents fonciers – Clients & Partenaires

En bref L’API Hypothèques en ligne permet aux professionnels d’automatiser les commandes de documents fonciers — états hypothécaires, copies d’actes, documents de copropriété — depuis leurs propres systèmes. Authentification OAuth 2.0 JWT Bearer. Environnements sandbox et production disponibles.

Documentation d’intégration

Automatisez vos commandes de documents fonciers.

L’API Hypothèques en ligne offre un accès sécurisé pour commander, suivre et récupérer vos documents immobiliers directement depuis vos systèmes.

⬇ Télécharger la spécification OpenAPI (YAML) Import direct dans Postman, Swagger UI ou pour la génération de clients SDK.

Environnements

Configuration

L’authentification s’effectue via OAuth 2.0 JWT Bearer.
Le JWT doit être généré et signé côté client avec un certificat, puis échangé contre un access_token via l’endpoint /oauth.
Les APIs métier utilisent ensuite cet access_token pour réaliser les demandes.

Clé Valeur
Base URL (production) https://api.hypotheques-en-ligne.fr/
Base URL (sandbox) https://api-sandbox.hypotheques-en-ligne.fr/
Contactez Hypothèques en ligne afin d’activer l’accès aux APIs.

Authentification

POST
/oauth
Obtention d’un access token (JWT Bearer)

Échange un JWT signé côté client contre un access_token utilisable sur l’ensemble des APIs métier.

Type Paramètres Notes
En-têtes (oblig.) Content-Type: application/x-www-form-urlencoded
Body (oblig.) grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<token JWT signé côté client>		 assertion contient le JWT signé avec la clé privée

Exemple de requête (curl)

curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/oauth" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  --data-urlencode "assertion=<JWT_signé_côté_client>"

Exemple de réponse JSON

{
  "access_token": "00Dxx0000000001!AQcAQ...",
  "token_type": "Bearer"
}

APIs

Chaque réponse des APIs métiers POST retourne un jobId (identifiant unique de la commande), réutilisable avec GET /v1/commandes/{jobId} pour en suivre le statut et récupérer le lien de dossier partagé.

POST
/v1/commandes/ehf-multi
État hypothécaire multi-entrées (cadastrale, identité, combinée)

Cet endpoint unifié permet de commander un état hypothécaire selon trois modes de recherche. La recherche cadastrale interroge le fichier immobilier à partir de références de parcelles (jusqu’à 12) ou, en copropriété, à partir d’assises cadastrales et de numéros de lots. La recherche par identité interroge le fichier à partir de personnes physiques ou morales (jusqu’à 3 au total). La recherche combinée croise des parcelles et des personnes dans une même commande — en mode exhaustif (tous les résultats liés aux parcelles et aux personnes) ou ciblé (uniquement les résultats à l’intersection des parcelles et des personnes). Pour les départements d’Alsace-Moselle (57, 67, 68), soumis au régime du livre foncier, seule la recherche cadastrale est autorisée.



Notes techniques

Paramètre Valeur
Encodage UTF-8. Les caractères accentués sont acceptés dans les noms de communes, de personnes et de raisons sociales (ex : "SAINT-DENIS-LÈS-BOURG").
Taille max. du body Pas de limite stricte. Le body maximal correspond à 12 parcelles + 3 personnes, soit environ 5 Ko.
Timeout recommandé 10 secondes. Le temps de réponse constaté est de 1 à 3 secondes.
Référentiel des communes Les valeurs de localisation_bien, lieu_naissance et code_postal_ville doivent correspondre au référentiel Hypothèques en ligne (format "CP VILLE"). Ce référentiel est communiqué au partenaire lors de la mise en place de l’intégration.
Spécification OpenAPI Un fichier openapi.yaml (OpenAPI 3.0) est disponible pour import direct dans Postman, Swagger UI ou pour la génération automatique de clients SDK.



En-têtes

En-tête Valeur Notes
Content-Type application/json Obligatoire.
Authorization Bearer <access_token> Obligatoire. Token obtenu via POST /oauth.



Paramètres généraux

Paramètre Type Obligatoire Description
numero_commande_partenaire string Oui Identifiant unique de la commande côté partenaire. Sert de clé d’idempotence : si un même numéro est envoyé une seconde fois, l’API retourne l’erreur DUPLICATE_VALUE sans créer de doublon.
localisation_bien string Oui Commune au format "CP VILLE" — code postal à 5 chiffres suivi de la ville en majuscules (ex : "01000 BOURG-EN-BRESSE", "01000 SAINT-DENIS-LÈS-BOURG"). La valeur doit correspondre au référentiel Hypothèques en ligne, communiqué lors de la mise en place de l’intégration.
type_recherche string Oui Mode de recherche : "cadastrale", "identite" ou "combinee". Voir la matrice des combinaisons ci-dessous.
type_combinee string Si combinée Obligatoire quand type_recherche = "combinee". Valeurs possibles :
— "exhaustive" : l’API retourne tous les résultats liés aux parcelles et tous les résultats liés aux personnes (union des résultats).
— "ciblee" : l’API retourne uniquement les résultats situés à l’intersection des parcelles et des personnes (résultats croisés).
copropriete boolean Non Défaut : false. Si true, le body doit contenir des tableaux assises[] + lots[] au lieu de parcelles[]. Disponible pour cadastrale et combinee. Interdit pour identite.
filtre_dernier_proprietaire_connu boolean Non Défaut : false. Limite la délivrance au dernier propriétaire connu. Disponible uniquement pour type_recherche = "cadastrale".
reference_partenaire string Non Référence interne libre du partenaire (ex : numéro de dossier client).
analyse_ehf boolean Non Défaut : false. Si true, déclenche l’analyse automatique de l’état hypothécaire par Intellig’IA une fois le document reçu.



Objet parcelles[] — recherche cadastrale hors copropriété

Tableau de 1 à 12 parcelles. Requis si type_recherche = "cadastrale" ou "combinee" et copropriete = false. Ne pas envoyer si copropriete = true.

Champ Type Obligatoire Format Description
section_cadastrale string Oui 1-2 caractères alphanumériques Section cadastrale (ex : "A", "BJ", "2E").
numero_parcelle string Oui 1-4 chiffres Numéro de parcelle (ex : "42", "1562").
prefixe string Non 3 chiffres Préfixe cadastral (ex : "000", "154"). Nécessaire pour certaines communes multi-cadastrales.



Objet assises[] — copropriété : assiette cadastrale

Tableau de 1 à 5 assises. Requis si copropriete = true et type_recherche = "cadastrale" ou "combinee".

Champ Type Obligatoire Format Description
section_cadastrale string Oui 1-2 caractères alphanumériques Section cadastrale de l’assise.
numero_parcelle string Oui 1-4 chiffres Numéro de parcelle de l’assise.
prefixe string Non 3 chiffres Préfixe cadastral de l’assise.



Objet lots[] — copropriété : numéros de lots

Tableau de 1 à 12 lots. Requis si copropriete = true et type_recherche = "cadastrale" ou "combinee". Chaque lot doit comporter au moins l’un des deux champs.

Champ Type Obligatoire Format Description
numero_lot string Conditionnel 1-7 chiffres Numéro de lot de copropriété. Obligatoire si volume n’est pas fourni.
volume string Conditionnel 1-7 chiffres Numéro de lot volumétrique. Obligatoire si numero_lot n’est pas fourni.



Objet personnes_physiques[] — personnes physiques

Tableau de 0 à 3 personnes physiques. Requis si type_recherche = "identite" ou "combinee".

Champ Type Obligatoire Format Description
nom_personne string Oui — Nom de famille.
prenom_1 string Oui — Premier prénom.
prenom_2 string Non — Deuxième prénom.
date_naissance string Oui JJ/MM/AAAA Date de naissance (ex : "15/03/1975").
lieu_naissance string Oui "CP VILLE" Lieu de naissance (ex : "01090 MONTMERLE-SUR-SAÔNE"). Valeur issue du référentiel (voir Notes techniques).
pays_naissance string Oui — Pays de naissance (ex : "France", "Italie").



Objet personnes_morales[] — personnes morales

Tableau de 0 à 3 personnes morales. Requis si type_recherche = "identite" ou "combinee". Le total personnes physiques + personnes morales ne peut pas dépasser 3.

Champ Type Obligatoire Format Description
raison_sociale string Oui — Raison sociale de l’entreprise, SCI ou association.
siren string Oui 9 chiffres Numéro SIREN (ex : "123456789").
code_postal_ville string Oui "CP VILLE" Siège social (ex : "01100 BELLIGNAT"). Valeur issue du référentiel (voir Notes techniques).



Combinaisons autorisées selon type_recherche

Ce tableau résume quels paramètres sont requis (✅), autorisés ou interdits (❌) selon le type de recherche choisi. En mode copropriété (copropriete = true), les parcelles[] sont remplacées par assises[] + lots[].

type_recherche parcelles[]
ou assises[]+lots[]		 personnes_*[] copropriete filtre_dernier_
proprietaire_connu		 type_combinee
cadastrale ✅ requis ❌ interdit ✅ autorisé ✅ autorisé —
identite ❌ interdit ✅ requis ❌ interdit ❌ interdit —
combinee ✅ requis ✅ requis ✅ autorisé ❌ interdit ✅ requis
Restriction Alsace-Moselle — Les communes des départements 57 (Moselle), 67 (Bas-Rhin) et 68 (Haut-Rhin) relèvent du régime du livre foncier. Seule la recherche "cadastrale" est autorisée. Les types "identite" et "combinee" retourneront l’erreur ALSACE_MOSELLE_RESTRICTION.



Calcul des débours

Les débours correspondent aux frais de réquisition auprès du service de publicité foncière. Ils sont calculés automatiquement par l’API et retournés dans le champ debours de la réponse (en euros). Le tarif appliqué dépend du type de recherche, du nombre d’éléments et de la localisation.

Situation Formule Exemple
Cadastrale, hors copropriété 12 € × nombre de parcelles 3 parcelles → 36 €
Cadastrale, copropriété 12 € × nombre de lots 2 lots → 24 €
Identité 12 € × nombre de personnes (PP + PM) 1 PP + 1 PM → 24 €
Combinée exhaustive, hors copro (12 € × parcelles) + (12 € × personnes) 2 parcelles + 1 personne → 36 €
Combinée exhaustive, copro (12 € × lots) + (12 € × personnes) 3 lots + 1 personne → 48 €
Combinée ciblée 12 € forfait + 2 € × max(0, nb_références − 5) 8 parcelles → 12 + 2×3 = 18 €
Alsace-Moselle (dép. 57, 67, 68) 7 € × nombre de parcelles ou lots 3 parcelles → 21 €

Pour la combinée ciblée, nb_références correspond au nombre de parcelles (ou de lots en copropriété).



Exemples de requêtes

Requête minimale — 1 parcelle cadastrale

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0001",
  "localisation_bien": "01000 BOURG-EN-BRESSE",
  "type_recherche": "cadastrale",
  "parcelles": [
    {"section_cadastrale": "BJ", "numero_parcelle": "42"}
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0001",
  "localisation_bien": "01000 BOURG-EN-BRESSE",
  "type_recherche": "cadastrale",
  "parcelles": [
    {"section_cadastrale": "BJ", "numero_parcelle": "42"}
  ]
}'

Exemple 2 — Cadastrale multi-parcelles avec filtre et analyse Intellig’IA

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0002",
  "reference_partenaire": "DOSSIER-ABC",
  "localisation_bien": "01100 OYONNAX",
  "type_recherche": "cadastrale",
  "filtre_dernier_proprietaire_connu": true,
  "analyse_ehf": true,
  "parcelles": [
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "123"},
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "124"},
    {"prefixe": "000", "section_cadastrale": "B", "numero_parcelle": "7"}
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0002",
  "reference_partenaire": "DOSSIER-ABC",
  "localisation_bien": "01100 OYONNAX",
  "type_recherche": "cadastrale",
  "filtre_dernier_proprietaire_connu": true,
  "analyse_ehf": true,
  "parcelles": [
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "123"},
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "124"},
    {"prefixe": "000", "section_cadastrale": "B", "numero_parcelle": "7"}
  ]
}'

Exemple 3 — Copropriété (1 assise, 2 lots)

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0003",
  "localisation_bien": "01100 ARBENT",
  "type_recherche": "cadastrale",
  "copropriete": true,
  "assises": [
    {"prefixe": "000", "section_cadastrale": "AB", "numero_parcelle": "15"}
  ],
  "lots": [
    {"numero_lot": "42", "volume": "3"},
    {"numero_lot": "43"}
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0003",
  "localisation_bien": "01100 ARBENT",
  "type_recherche": "cadastrale",
  "copropriete": true,
  "assises": [
    {"prefixe": "000", "section_cadastrale": "AB", "numero_parcelle": "15"}
  ],
  "lots": [
    {"numero_lot": "42", "volume": "3"},
    {"numero_lot": "43"}
  ]
}'

Exemple 4 — Recherche par identité : personne physique

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0004",
  "localisation_bien": "01090 MONTMERLE-SUR-SAÔNE",
  "type_recherche": "identite",
  "personnes_physiques": [
    {
      "nom_personne": "DUPONT",
      "prenom_1": "Jean",
      "prenom_2": "Pierre",
      "date_naissance": "15/03/1975",
      "lieu_naissance": "01000 BOURG-EN-BRESSE",
      "pays_naissance": "France"
    }
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0004",
  "localisation_bien": "01090 MONTMERLE-SUR-SAÔNE",
  "type_recherche": "identite",
  "personnes_physiques": [
    {
      "nom_personne": "DUPONT",
      "prenom_1": "Jean",
      "prenom_2": "Pierre",
      "date_naissance": "15/03/1975",
      "lieu_naissance": "01000 BOURG-EN-BRESSE",
      "pays_naissance": "France"
    }
  ]
}'

Exemple 5 — Recherche par identité : personne morale

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0005",
  "localisation_bien": "01100 BELLIGNAT",
  "type_recherche": "identite",
  "personnes_morales": [
    {
      "raison_sociale": "SCI LES OLIVIERS",
      "siren": "123456789",
      "code_postal_ville": "01100 BELLIGNAT"
    }
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0005",
  "localisation_bien": "01100 BELLIGNAT",
  "type_recherche": "identite",
  "personnes_morales": [
    {
      "raison_sociale": "SCI LES OLIVIERS",
      "siren": "123456789",
      "code_postal_ville": "01100 BELLIGNAT"
    }
  ]
}'

Exemple 6 — Recherche combinée exhaustive (parcelles + personne physique)

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0006",
  "localisation_bien": "01100 GROISSIAT",
  "type_recherche": "combinee",
  "type_combinee": "exhaustive",
  "parcelles": [
    {"section_cadastrale": "AK", "numero_parcelle": "201"},
    {"section_cadastrale": "AK", "numero_parcelle": "202"}
  ],
  "personnes_physiques": [
    {
      "nom_personne": "MARTIN",
      "prenom_1": "Sophie",
      "date_naissance": "22/07/1980",
      "lieu_naissance": "01110 HAUTEVILLE-LOMPNES",
      "pays_naissance": "France"
    }
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0006",
  "localisation_bien": "01100 GROISSIAT",
  "type_recherche": "combinee",
  "type_combinee": "exhaustive",
  "parcelles": [
    {"section_cadastrale": "AK", "numero_parcelle": "201"},
    {"section_cadastrale": "AK", "numero_parcelle": "202"}
  ],
  "personnes_physiques": [
    {
      "nom_personne": "MARTIN",
      "prenom_1": "Sophie",
      "date_naissance": "22/07/1980",
      "lieu_naissance": "01110 HAUTEVILLE-LOMPNES",
      "pays_naissance": "France"
    }
  ]
}'

Exemple 7 — Recherche combinée ciblée en copropriété

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0007",
  "localisation_bien": "01110 HAUTEVILLE-LOMPNES",
  "type_recherche": "combinee",
  "type_combinee": "ciblee",
  "copropriete": true,
  "assises": [
    {"section_cadastrale": "CL", "numero_parcelle": "88"}
  ],
  "lots": [
    {"numero_lot": "1"},
    {"numero_lot": "2"},
    {"numero_lot": "3"}
  ],
  "personnes_morales": [
    {
      "raison_sociale": "SARL IMMOBILIERE AZUR",
      "siren": "987654321",
      "code_postal_ville": "01110 HAUTEVILLE-LOMPNES"
    }
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0007",
  "localisation_bien": "01110 HAUTEVILLE-LOMPNES",
  "type_recherche": "combinee",
  "type_combinee": "ciblee",
  "copropriete": true,
  "assises": [
    {"section_cadastrale": "CL", "numero_parcelle": "88"}
  ],
  "lots": [
    {"numero_lot": "1"},
    {"numero_lot": "2"},
    {"numero_lot": "3"}
  ],
  "personnes_morales": [
    {
      "raison_sociale": "SARL IMMOBILIERE AZUR",
      "siren": "987654321",
      "code_postal_ville": "01110 HAUTEVILLE-LOMPNES"
    }
  ]
}'

Exemple 8 — Combinée exhaustive charge maximale (12 parcelles + 2 PP + 1 PM)

Cet exemple montre la capacité maximale de l’endpoint : 12 parcelles et 3 personnes dans une même commande. Les débours sont calculés automatiquement : (12 × 12 €) + (3 × 12 €) = 180 €.

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0008",
  "localisation_bien": "01100 MARTIGNAT",
  "type_recherche": "combinee",
  "type_combinee": "exhaustive",
  "analyse_ehf": true,
  "parcelles": [
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "101"},
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "102"},
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "103"},
    {"prefixe": "000", "section_cadastrale": "B", "numero_parcelle": "201"},
    {"prefixe": "000", "section_cadastrale": "B", "numero_parcelle": "202"},
    {"prefixe": "000", "section_cadastrale": "B", "numero_parcelle": "203"},
    {"prefixe": "000", "section_cadastrale": "C", "numero_parcelle": "301"},
    {"prefixe": "000", "section_cadastrale": "C", "numero_parcelle": "302"},
    {"prefixe": "000", "section_cadastrale": "C", "numero_parcelle": "303"},
    {"prefixe": "000", "section_cadastrale": "D", "numero_parcelle": "401"},
    {"prefixe": "000", "section_cadastrale": "D", "numero_parcelle": "402"},
    {"prefixe": "000", "section_cadastrale": "D", "numero_parcelle": "403"}
  ],
  "personnes_physiques": [
    {
      "nom_personne": "DUPONT",
      "prenom_1": "Jean",
      "date_naissance": "15/03/1975",
      "lieu_naissance": "01000 BOURG-EN-BRESSE",
      "pays_naissance": "France"
    },
    {
      "nom_personne": "MARTIN",
      "prenom_1": "Marie",
      "prenom_2": "Claire",
      "date_naissance": "22/07/1980",
      "lieu_naissance": "01100 OYONNAX",
      "pays_naissance": "France"
    }
  ],
  "personnes_morales": [
    {
      "raison_sociale": "SCI DU PARC",
      "siren": "456789123",
      "code_postal_ville": "01100 MARTIGNAT"
    }
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0008",
  "localisation_bien": "01100 MARTIGNAT",
  "type_recherche": "combinee",
  "type_combinee": "exhaustive",
  "analyse_ehf": true,
  "parcelles": [
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "101"},
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "102"},
    {"prefixe": "000", "section_cadastrale": "A", "numero_parcelle": "103"},
    {"prefixe": "000", "section_cadastrale": "B", "numero_parcelle": "201"},
    {"prefixe": "000", "section_cadastrale": "B", "numero_parcelle": "202"},
    {"prefixe": "000", "section_cadastrale": "B", "numero_parcelle": "203"},
    {"prefixe": "000", "section_cadastrale": "C", "numero_parcelle": "301"},
    {"prefixe": "000", "section_cadastrale": "C", "numero_parcelle": "302"},
    {"prefixe": "000", "section_cadastrale": "C", "numero_parcelle": "303"},
    {"prefixe": "000", "section_cadastrale": "D", "numero_parcelle": "401"},
    {"prefixe": "000", "section_cadastrale": "D", "numero_parcelle": "402"},
    {"prefixe": "000", "section_cadastrale": "D", "numero_parcelle": "403"}
  ],
  "personnes_physiques": [
    {
      "nom_personne": "DUPONT",
      "prenom_1": "Jean",
      "date_naissance": "15/03/1975",
      "lieu_naissance": "01000 BOURG-EN-BRESSE",
      "pays_naissance": "France"
    },
    {
      "nom_personne": "MARTIN",
      "prenom_1": "Marie",
      "prenom_2": "Claire",
      "date_naissance": "22/07/1980",
      "lieu_naissance": "01100 OYONNAX",
      "pays_naissance": "France"
    }
  ],
  "personnes_morales": [
    {
      "raison_sociale": "SCI DU PARC",
      "siren": "456789123",
      "code_postal_ville": "01100 MARTIGNAT"
    }
  ]
}'
Réponse
{
  "success": true,
  "jobId": "500Aa000001xYzZIAU",
  "debours": 180,
  "errors": []
}

Exemple 9 — Alsace-Moselle (tarif réduit, cadastrale uniquement)

Pour les départements 57, 67 et 68 (livre foncier), seule la recherche cadastrale est autorisée. Le tarif des débours est réduit à 7 € par parcelle (au lieu de 12 €). Les types identite et combinee retourneront l’erreur ALSACE_MOSELLE_RESTRICTION.

Body JSON
{
  "numero_commande_partenaire": "CMD-2026-0009",
  "localisation_bien": "67000 STRASBOURG",
  "type_recherche": "cadastrale",
  "parcelles": [
    {"section_cadastrale": "12", "numero_parcelle": "45"},
    {"section_cadastrale": "12", "numero_parcelle": "46"},
    {"section_cadastrale": "15", "numero_parcelle": "8"}
  ]
}
curl
curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/ehf-multi" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
  "numero_commande_partenaire": "CMD-2026-0009",
  "localisation_bien": "67000 STRASBOURG",
  "type_recherche": "cadastrale",
  "parcelles": [
    {"section_cadastrale": "12", "numero_parcelle": "45"},
    {"section_cadastrale": "12", "numero_parcelle": "46"},
    {"section_cadastrale": "15", "numero_parcelle": "8"}
  ]
}'
Réponse
{
  "success": true,
  "jobId": "500Aa000001xYzZIAU",
  "debours": 21,
  "errors": []
}



Réponses

L’API retourne toujours un code HTTP 200 avec un Content-Type: application/json; charset=UTF-8. Le champ success dans le corps JSON indique si la commande a été créée (true) ou si des erreurs ont été détectées (false).

Succès

{
  "success": true,
  "jobId": "500Aa000001xYzZIAU",
  "debours": 36,
  "errors": []
}

jobId est l’identifiant de la commande créée, réutilisable avec GET /v1/commandes/{jobId} pour suivre l’avancement et récupérer le lien de dossier partagé. debours indique le montant des débours calculés (en euros).

Erreur

{
  "success": false,
  "jobId": null,
  "debours": null,
  "errors": [
    {
      "code": "ALSACE_MOSELLE_RESTRICTION",
      "message": "Départements 57/67/68: cadastrale uniquement.",
      "field": "type_recherche"
    }
  ]
}

Le tableau errors peut contenir plusieurs erreurs. Chaque erreur indique un code, un message explicatif et le field concerné.



Codes d’erreur

Code Description
AUTH_REQUIRED Header Authorization absent.
INVALID_TOKEN Le token JWT fourni est invalide ou expiré.
INVALID_JSON Corps de la requête JSON vide ou syntaxiquement incorrect.
MISSING_FIELD Champ obligatoire manquant (le champ est précisé dans field).
INVALID_VALUE Valeur invalide : format incorrect, commune absente du référentiel, date mal formée, SIREN non conforme.
INVALID_COMBINATION Combinaison de paramètres interdite (ex : personnes dans une recherche cadastrale, parcelles dans une recherche par identité, copropriété avec identité).
LIMIT_EXCEEDED Nombre d’éléments dépassé : max 12 parcelles, max 5 assises, max 12 lots, max 3 personnes au total.
ALSACE_MOSELLE_RESTRICTION Les départements 57, 67 et 68 (livre foncier) n’autorisent que la recherche cadastrale.
DUPLICATE_VALUE Le numero_commande_partenaire a déjà été utilisé par cet utilisateur.
LOT_INCOMPLETE Un lot en copropriété ne contient ni numero_lot ni volume.
SERVER_ERROR Erreur interne. Contactez le support si le problème persiste.

POST
/v1/commandes/acte
Copie d’acte notarié

Crée une commande de copie d’acte notarié (acte de vente, donation, succession, partage, …) à partir de sa référence d’enliassement.

Type Paramètres Notes
En-têtes (oblig.) Content-Type: application/json, Authorization: Bearer <access_token> access_token obtenu préalablement via /oauth
Obligatoires numero_commande_partenaire, localisation_bien, date_formalite, volume, numero, numero_sages localisation_bien issue du référentiel Hypothèques en ligne.
numero_commande_partenaire est le numéro unique de la commande côté client/partenaire.
Facultatifs reference_partenaire —
Contraintes Format date : JJ/MM/AAAA.

Exemple de JSON d’envoi (body)

{
  "numero_commande_partenaire": "CMD-2025-0006",
  "reference_partenaire": "REF-XYZ",
  "localisation_bien": "94100 SAINT-MAUR-DES-FOSSÉS",
  "date_formalite": "15/09/2003",
  "volume": "2003P",
  "numero": "5678",
  "numero_sages": "9404P01"
}

Exemple de requête (curl)

curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/acte" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "numero_commande_partenaire": "CMD-2025-0006",
    "reference_partenaire": "REF-XYZ",
    "localisation_bien": "94100 SAINT-MAUR-DES-FOSSÉS",
    "date_formalite": "15/09/2003",
    "volume": "2003P",
    "numero": "5678",
    "numero_sages": "9404P01"
  }'

Exemple de réponse JSON

{
  "success": true,
  "jobId": "500xxxxxxxxxxxx",
  "errors": []
}

POST
/v1/commandes/doc-copro
Document de copropriété (RDC / EDD)

Crée une commande de document ou modificatif de copropriété (RDC : Règlement De Copropriété / EDD : État Descriptif de Division) à partir de sa référence d’enliassement.

Type Paramètres Notes
En-têtes (oblig.) Content-Type: application/json, Authorization: Bearer <access_token> access_token obtenu préalablement via /oauth
Obligatoires numero_commande_partenaire, localisation_bien, document_demande, date_formalite, volume, numero, numero_sages document_demande ∈ {RDC, EDD} ; localisation_bien issue du référentiel Hypothèques en ligne.
numero_commande_partenaire est le numéro unique de la commande côté client/partenaire.
Facultatifs reference_partenaire —
Contraintes Format date : JJ/MM/AAAA.

Exemple de JSON d’envoi (body)

{
  "numero_commande_partenaire": "CMD-2025-0007",
  "reference_partenaire": "REF-XYZ",
  "localisation_bien": "13400 AUBAGNE",
  "document_demande": "RDC",
  "date_formalite": "10/10/2019",
  "volume": "2019P",
  "numero": "345",
  "numero_sages": "9404P01"
}

Exemple de requête (curl)

curl -X POST "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/doc-copro" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "numero_commande_partenaire": "CMD-2025-0007",
    "reference_partenaire": "REF-XYZ",
    "localisation_bien": "13400 AUBAGNE",
    "document_demande": "RDC",
    "date_formalite": "10/10/2019",
    "volume": "2019P",
    "numero": "345",
    "numero_sages": "9404P01"
  }'

Exemple de réponse JSON

{
  "success": true,
  "jobId": "500xxxxxxxxxxxx",
  "errors": []
}

GET
/v1/commandes/{jobId}
Suivi d’une commande

Récupère le statut, l’avancement et le lien de dossier partagé associés à une commande existante.
Le paramètre {jobId} correspond à l’identifiant (Id) de la commande créée par les API métiers.

Type Paramètres Notes
En-têtes (oblig.) Content-Type: application/json,
Authorization: Bearer <access_token>		 access_token obtenu préalablement via
/oauth
URL (oblig.) {jobId} Identifiant de la commande
Body — Non requis

Exemple de requête (curl)

curl -X GET "https://api-sandbox.hypotheques-en-ligne.fr/v1/commandes/5008Z00000AbCdE" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>"

Exemple de réponse JSON

{
  "success": true,
  "jobId": "5008Z00000AbCdE",
  "status": "In Progress",
  "share_folder": "https://docs.hypotheques-en-ligne.fr/aZerTy_io-PqsdZg",
  "errors": []
}

Statuts de la commande

Statut Description
New Commande créée, en attente de traitement.
In Progress Commande en cours de traitement.
Awaiting Customer Attente d’une réponse client.
Closed Commande terminée, documents disponibles.
Cancelled Commande annulée.

Questions fréquentes

Comment accéder à l’API Hypothèques en ligne ?

L’accès à l’API est sur demande. Contactez Hypothèques en ligne pour activer votre accès. Un environnement sandbox est disponible pour tester l’intégration sans frais avant le passage en production. L’authentification s’effectue via OAuth 2.0 JWT Bearer.

Quels documents immobiliers sont disponibles via l’API ?

L’API permet de commander les principaux documents du catalogue : état hypothécaire, copie d’acte notarié, règlement de copropriété et état descriptif de division. Les résultats sont restitués directement dans le système appelant, sans intervention manuelle.

L’API est-elle compatible avec les logiciels immobiliers ?

Oui. L’API REST d’Hypothèques en ligne est conçue pour s’intégrer à tout logiciel immobilier : plateformes de transaction, outils de gestion loc