Documentation API Partenaire
Vue d'ensemble fonctionnelle de l'API MonHubImmo pour les réseaux immobiliers.
Introduction
L'API partenaire MonHubImmo permet aux réseaux immobiliers d'intégrer la plateforme directement dans leur système d'information. Toutes les opérations sont disponibles via une API REST standard.
URL de base
https://api.monhubimmo.fr/api/external/v1Format
JSON (requêtes et réponses)
Rate limiting
250 requêtes / minute
success (booléen). En cas de succès, la ressource est renvoyée sous son propre nom à la racine (users, property, searchAd…) : il n'y a pas de clé data. En cas d'échec, les champs sont error et message (ou details[] sur une erreur de validation). Les identifiants d'URL sont des ObjectId MongoDB, pas vos externalId.Authentification
Toutes les requêtes API doivent inclure votre clé API dans le header X-API-Key.
Obtenir vos clés
Contactez notre équipe via le formulaire de contact pour recevoir vos identifiants API (clé API et secret pour les webhooks).
curl -X GET "https://api.monhubimmo.fr/api/external/v1/users" \
-H "X-API-Key: votre-cle-api" \
-H "Content-Type: application/json"{
"success": true,
"users": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Gestion des utilisateurs
Créez et gérez les comptes de vos agents directement depuis votre SI. Chaque agent créé via l'API est automatiquement rattaché à votre réseau partenaire.
Créer un agent
Créez un compte pour un nouvel agent de votre réseau. Un email de bienvenue lui sera automatiquement envoyé. La validation automatique du compte et l'abonnement accordé à la création (Découverte, Standard ou Premium, sans paiement) sont définis dans la configuration de votre réseau partenaire. Le champ facultatif planpermet d'accorder un plan inférieur à un agent donné.
{
"email": "agent@monreseau.fr",
"firstName": "Marie",
"lastName": "Dupont",
"phone": "0612345678",
"externalId": "agent-123",
"plan": "essentiel",
"professionalInfo": {
"city": "Paris",
"postalCode": "75011",
"interventionRadius": 25,
"coveredCities": [
{ "city": "Paris", "postalCode": "75011" }
],
"yearsExperience": 8,
"personalPitch": "Bio de 250 à 1500 caractères — en dessous de 250, l'appel échoue en 422."
}
}professionalInfo est requis en entier à la création, avec au moins une commune dans coveredCities et un personalPitch de 250 à 1500 caractères — l'erreur la plus fréquente. Chaque couple ville / code postal est géocodé : un seul échec fait échouer tout l'appel (422 Geocoding error). Le champ userType n'est pas accepté : l'API ne crée que des agents.Lister les agents
Récupérez la liste de tous les agents de votre réseau avec pagination.
{
"success": true,
"users": [
{
"id": "507f1f77bcf86cd799439011",
"externalId": "agent-123",
"email": "agent@monreseau.fr",
"firstName": "Marie",
"lastName": "Dupont",
"isValidated": true,
"profileCompleted": true,
"createdAt": "2026-11-10T12:00:00.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 42,
"totalPages": 3
}
}Un agent n'a pas de champ status : son état se lit dans isValidated et profileCompleted. Filtres disponibles : email (partiel), externalId (exact), page, limit (défaut 20, maximum 100).
Activer / Désactiver un agent
Gérez le statut de vos agents. Un agent désactivé ne peut plus se connecter.
// Corps vide. :id est l'ObjectId renvoyé à la création.
{
"success": true,
"user": {
"id": "507f1f77bcf86cd799439011",
"email": "agent@monreseau.fr",
"firstName": "Marie",
"lastName": "Dupont",
"externalId": "agent-123",
"isValidated": true
},
"message": "User activated successfully"
}// Corps vide. Répond 400 « No change needed » si le compte
// est déjà dans l'état demandé.Gestion des biens immobiliers
Synchronisez automatiquement les biens de vos agents avec MonHubImmo. Publiez, mettez à jour et retirez des annonces programmatiquement.
Publier un bien
Créez une annonce pour un bien immobilier au nom d'un de vos agents.
{
"userId": "507f1f77bcf86cd799439011",
"externalId": "bien-456",
"title": "Appartement T3 lumineux — Paris 11e",
"propertyType": "Appartement",
"transactionType": "Vente",
"price": 450000,
"surface": 65,
"rooms": 3,
"city": "Paris",
"postalCode": "75011",
"sector": "Quartier Saint-Ambroise",
"description": "Bel appartement traversant de 50 caractères minimum, sinon l'appel échoue."
}userId est l'ObjectId de l'agent (pas son externalId), sector est requis, et la description fait au moins 50 caractères. Les énumérations d'un bien sont en français capitalisé : Appartement, Maison, Terrain, Local commercial, Bureaux et Vente / Location — à ne pas confondre avec le vocabulaire anglais des recherches acquéreurs. Le bien est créé en status: "draft" : un second appel est nécessaire pour le publier.Mettre à jour un bien
Modifiez les informations d'un bien existant (prix, description, statut...).
{
"price": 440000,
"status": "active"
}Statuts écrivables par le partenaire : draft, active, archived — ni sold ni rented. Modifier le prix d'un bien engagé dans une collaboration en cours répond 409 Conflict.
Essai gratuit terminé (403 TRIAL_ENDED) : pour un agent inscrit après l'activation de l'essai (14 jours, droits Standard) dont l'essai est terminé sans abonnement ni plan accordé par votre réseau, la création d'un bien ou d'une recherche et la mise en ligne (status: "active") d'un brouillon, d'une archive ou d'une recherche en pause sont refusées.
Restent acceptés : la modification et l'archivage de ses annonces, qui restent en ligne (une synchronisation peut toujours retirer un bien vendu), et toutes les lectures. Un agent à qui votre réseau accorde un plan n'est jamais concerné. Le refus n'est pas transitoire : il cesse quand l'agent s'abonne.
Consulter et retirer
Consultez les détails d'un bien, ou listez vos propres biens tous statuts confondus. Pour retirer un bien, archivez-le : l'API externe n'expose aucune méthode DELETE.
// Réponse : { "success": true, "property": { ... } }// Vos biens créés via l'API, brouillons et archivés compris.
// C'est le chemin pour retrouver l'ObjectId à partir de votre
// propre référence : properties[0].id{
"status": "archived"
}Recherches acquéreurs
Diffusez les critères de recherche de vos acquéreurs sur MonHubImmo. Le système de matching automatique rapproche les recherches avec les biens disponibles.
Diffuser une recherche
Créez une annonce de recherche acquéreur pour un de vos agents.
{
"userId": "507f1f77bcf86cd799439011",
"externalId": "recherche-789",
"title": "Recherche T3/T4 Paris 11e",
"description": "Description de 10 à 2000 caractères, requise.",
"projectType": "primary",
"propertyTypes": ["apartment"],
"budget": { "max": 500000, "ideal": 460000, "financingType": "loan" },
"minSurface": 55,
"location": {
"cities": ["Paris"],
"postalCodes": ["75011"],
"maxDistance": 10
}
}description est requise (10 à 2000 caractères) ; budget n'a pas de min (seulement max, ideal, financingType…) ; et location.departments n'existe pas — utilisez cities, postalCodes et maxDistance. Les types de bien d'une recherche sont en anglais minuscule : house, apartment, land, building, commercial. Contrairement à un bien, une recherche est créée directement en status: "active". Statuts écrivables : active, paused, archived.Matching automatique
Lorsqu'un bien correspond aux critères d'une recherche (ou inversement),MonHubImmo génère automatiquement une proposition de collaboration. Vous pouvez être notifié de ces matchings via webhooks.
Webhooks & Notifications
Configurez des webhooks pour recevoir des notifications en temps réel lorsque des événements importants se produisent sur MonHubImmo.
Événements disponibles
| Événement | Description |
|---|---|
property.created | Un bien a été publié |
property.updated | Un bien a été modifié |
property.deleted | Un bien a été supprimé |
property.status_changed | Le statut d'un bien a changé |
search_ad.created | Une recherche acquéreur a été diffusée |
search_ad.updated | Une recherche a été modifiée |
search_ad.deleted | Une recherche a été supprimée |
search_ad.status_changed | Le statut d'une recherche a changé |
lead.created | Un lead a été créé par un apporteur d'affaires |
lead.updated | Un lead a été modifié |
lead.deleted | Un lead a été supprimé |
lead.status_changed | Le statut d'un lead a changé |
Enveloppe : { event, timestamp, data }. L'API externe elle-même n'émet que property.created, property.updated, search_ad.created et search_ad.updated — les autres proviennent du parcours applicatif. En particulier, un PUT /properties/:id qui change le statut émet property.updated, jamais property.status_changed : abonnez-vous aux deux si vous suivez les statuts.
Signature HMAC-SHA256
Chaque webhook inclut un header X-Webhook-Signature de la forme sha256=<hex>, calculé en HMAC-SHA256 sur le corps brut de la requête avec votre signing secret. Signez bien le corps brut : re-sérialiser le JSON déjà analysé produit d'autres octets, donc une autre signature. Comparez en temps constant.
const crypto = require('crypto');
// Conserver le corps brut (Buffer), pas l'objet analysé
app.use('/webhooks/mhi', express.raw({ type: 'application/json' }));
app.post('/webhooks/mhi', (req, res) => {
const expected = 'sha256=' + crypto
.createHmac('sha256', SIGNING_SECRET)
.update(req.body)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(req.get('X-Webhook-Signature') || '');
// timingSafeEqual exige des longueurs égales : les comparer d'abord
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).send('Signature invalide');
}
const { event, timestamp, data } = JSON.parse(req.body.toString('utf8'));
res.status(200).end(); // répondre vite, traiter ensuite
});Retry automatique
En cas d'échec de livraison (réponse non-2xx ou timeout), MonHubImmo retente automatiquement : 3 tentatives au maximum, avec des délais de 0 s, 10 s puis 60 s — l'ensemble se termine donc en ~70 s. Chaque tentative a un timeout de 10 s : répondez 2xx immédiatement et traitez l'événement en arrière-plan, sinon la livraison est comptée en échec. Le signing secret n'est affiché qu'une seule fois, à la création du webhook, et ne se renouvelle pas en place : pour le changer, supprimez le webhook et recréez-le.
Connexion SSO
Permettez à vos agents de se connecter à MonHubImmo directement depuis votre plateforme, sans ressaisir leurs identifiants.
JWT partenaire
Générez un JWT côté serveur avec votre secret partenaire et redirigez l'agent vers MonHubImmo. Le token est vérifié et l'agent est connecté automatiquement.
const jwt = require('jsonwebtoken');
// Les claims sont userId + partnerId, tous deux obligatoires.
// Ce sont des ObjectId MonHubImmo, pas des externalId.
const token = jwt.sign(
{
userId: '507f1f77bcf86cd799439011', // l'agent
partnerId: '507f1f77bcf86cd799439022' // votre réseau
},
PARTNER_JWT_SECRET,
{ algorithm: 'HS256', expiresIn: '5m' }
);
// Puis, côté serveur :
// POST https://api.monhubimmo.fr/api/auth/partner-login
// { "token": "<jwt>" }
// La réponse pose les cookies de session ; redirigez ensuite
// le navigateur vers https://app.monhubimmo.frToken has already been used. Votre JWT secret est différent de votre clé API. Contrairement à la clé API, qui est hachée et n'est lisible qu'à sa création, le JWT secret reste lisible dans votre portail partenaire puisque vous devez signer avec lui.Codes d'erreur
L'API utilise les codes HTTP standards pour indiquer le succès ou l'échec d'une requête.
| Code | Statut | Description |
|---|---|---|
200 | OK | Requête réussie |
201 | Created | Ressource créée avec succès |
400 | Bad Request | Paramètres invalides ou manquants |
401 | Unauthorized | Clé API manquante ou invalide |
403 | Forbidden | Accès refusé à cette ressource |
403 | Trial ended | Code TRIAL_ENDED : essai gratuit de l'agent terminé sans abonnement, création ou mise en ligne d'une annonce refusée (modification et archivage restent acceptés) |
404 | Not Found | Ressource non trouvée |
409 | Conflict | Email déjà utilisé, ou prix modifié sur un bien engagé dans une collaboration en cours |
422 | Unprocessable | Erreur de validation des données |
429 | Too Many Requests | Limite de requêtes dépassée (250/min) |
500 | Server Error | Erreur interne du serveur |
{
"success": false,
"error": "Validation error",
"details": [
{ "field": "email", "message": "Email invalide" },
{
"field": "professionalInfo.personalPitch",
"message": "La bio doit contenir au moins 250 caractères"
}
]
}Une erreur de validation n'a pas de champ message : lisez details[], qui nomme chaque champ fautif. Les autres erreurs (404, 409, géocodage, image) portent bien un message.
Prêt à intégrer votre réseau ?
Contactez notre équipe pour obtenir vos clés API et démarrer l'intégration de votre réseau.
Nous contacter