id MongoDB ou son customId métier, avec ses contacts liés.
Endpoint
URL :/external-integration/rental
Méthode : GET
Authentification : Requiert un token LinkedAPI avec scope externalIntegration (GET) et agencyGroup configuré.
Clé requise : toutes les clés (lecture seule suffit). Voir Types de clé.
Headers
Query Parameters
Exemple de requête
Logique de fonctionnement
- Validation des params : Vérifie qu’un seul des deux paramètres est fourni et valide son format
- Recherche scopée : Filtre sur
agencyGroup === linkedAPI.agencyGroupETagency ∈ linkedAPI.agencies - Récupération des contacts : Si location trouvée, fetch des contacts liés (re-scopés sur les mêmes agences)
- Sérialisation : Tous les champs publics renseignés sur la fiche sont retournés. Les champs non renseignés sont absents de la réponse (pas
null). Le contact principal de la location est exposé viarental.mainContact(ID), le détail complet du contact est dans la clécontactsau top-level.
Réponse de succès
Code :200
Location trouvée
Note de migration : les champs
customId et step sont retournés à partir du
déploiement de cette version. Si votre intégration utilisait cette route
avant, ces deux champs étaient absents — vérifier que vous les récupérez
désormais.Location non trouvée ou hors scope
Une fiche existant dans une autre
agencyGroup retourne ce même payload
(null). Pas de différenciation possible côté client entre “n’existe pas” et
“pas autorisé”.Champs de la réponse
Top-level rental
Toujours présents (si la location existe) :
Présents uniquement si renseignés (sinon clé absente, pas
null) :
property
property.addressData (présent si la fiche a une adresse — adresse splittée) :
Autres champs
property retournés s’ils sont renseignés (même set que pour GET Sale) : mainType (apartment, house, building, …), developmentType (old/new), size, floor, rooms, bedrooms, bathrooms, toilets, kitchenType, surfaces (floorSurface, livingSurface, usefulSurface, …), extérieurs (balconyAmount, terraceAmount, gardenAmount, …), équipements (hasElevator, hasFireplace, isAirConditioning, …), DPE (DPENumber, DPEEnergyValue, DPEEnergyTag, DPEGESValue, DPEGESTag, DPEDate), copropriété (isCollectiveOwnership, collectiveMonthlyCost, numberOfLots), availabilityDate, etc. Biens professionnels : vatRegime (subject soumis à TVA, exempt non soumis) et propertyTaxResponsibility (taxe foncière à la charge du bailleur, owner, ou du preneur, tenant).
contacts (top-level)
Liste des contacts liés à la location. Le premier élément correspond au mainContact au top-level. Mêmes champs que pour les autres routes externes (cf. GET Sale).
Réponses d’erreur
- Aucun paramètre fourni :
400 Bad Request
- Les deux paramètres fournis :
400 Bad Request
idinvalide :400 Bad Request
customIdinvalide :400 Bad Request
- LinkedAPI agencyGroup manquant :
400 Bad Request
- Header
Authorizationabsent, ou IP non whitelistée sur une clé sécurisée :403 Not authorized to access this resource
- Token invalide :
401 Invalid bearer token
Notes importantes
- Scope strict : La fiche n’est retournée que si elle appartient à la
agencyGroupdu token ET à une desagencieslistées dans le LinkedAPI. Aucune fuite cross-group, même avec unidMongo connu d’une autre agence. - Pas de différenciation 404 vs 403 : Une fiche hors scope retourne le même
nullqu’une fiche inexistante. Choix volontaire pour ne pas leak l’existence de fiches d’autres agences. - Contacts re-scopés : Les contacts liés sont eux-mêmes filtrés sur
agency ∈ linkedAPI.agenciespour éviter les fuites cross-group. - Idempotence : L’endpoint est purement en lecture. Aucune modification d’état.
- Cas d’usage typique : Réception d’une notification de nouveau lead → extraction du
customIdouiddu mail → appel GET → récupération email/nom/adresse du bien pour automatisation (Make, Zapier, etc.). - Champs absents vs
null: les champs non renseignés sur la fiche n’apparaissent pas du tout dans la réponse — ils ne sont pas retournés ànull. Côté client, traiter chaque champ comme optionnel. - Lien vers le bailleur : pour récupérer les coordonnées du bailleur principal, faire
GET /external-integration/contactavec l’IDmainContact.
Rate limits
Cette route est limitée à 500 req / minute par groupe d’agences (bucket dédié, indépendant des autres routes).- Headers présents sur toutes les réponses :
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset(secondes avant reset). - Dépassement →
429 Too Many Requestsavec headerRetry-After(secondes) :
- Si vous atteignez régulièrement la limite, contactez le support pour évaluer un relèvement sur votre token.