Documentation
Contact
Référence API

Migrer de la v3 vers la v3.1

La version 3.1 de l'API MLS CONNECT est servie sous le préfixe /api/v3.1/. Elle est en production depuis le 22 septembre 2026. Le préfixe /api/v3/ continue de servir la version 3.0, sans aucun changement, jusqu'à la sortie d'une version majeure. Vous migrez donc quand vous le décidez : rien ne change pour vous tant que vous n'avez pas modifié vos URLs.
Cette page liste tout ce qui diffère entre les deux versions et la marche à suivre. La description complète de chaque route et de chaque champ est dans la documentation de référence, qui décrit la version 3.1.

Ce qui change

Quatre champs changent de forme entre la 3.0 et la 3.1. Tout le reste — routes, authentification, pagination, filtres, codes HTTP, format d'écriture — est identique.

Surfaces formatées : un node par locale

Toutes les surfaces mises en forme deviennent un objet avec une clé par locale, sur le modèle de price_formatted. Le symbole d'unité suit la locale : pi² en fr-CA, ft² ailleurs pour les pieds carrés ; m² partout pour les mètres carrés.
Champs concernés :
  • area_formatted à la racine des résultats de recherche
  • area_converted.square-meter.area_formatted et area_converted.square-foot.area_formatted
  • surface_areas.formatted.* dans le détail d'un bien
  • rooms_details[].area_formatted et lot_details[].area_formatted 
// v3.0
"area_formatted": "1 200 ft²"

// v3.1
"area_formatted": {
  "fr":    "1 200 ft²",
  "fr-CA": "1 200 pi²",
  "en":    "1 200 ft²",
  "…":     "…"
}
À faire : lire la clé de la locale que vous affichez, par exemple area_formatted["fr-CA"]. Si vous n'utilisez pas ce champ, rien à faire.

Viager : des nombres à la place d'objets monétaires

life_lease.venal_value et life_lease.life_annuity sont servis comme price, sold_price et rent : un nombre, ou null quand la valeur est absente. La devise est celle de financial.currency.
// v3.0
"venal_value": {"cents": 25000000, "currency_iso": "eur"}

// v3.1
"venal_value": 250000.0
À faire : remplacer la lecture de cents / 100 par la lecture directe du nombre. L'écriture (création et mise à jour) attendait déjà un nombre en 3.0 : rien ne change côté envoi.

Adresse : le numéro d'appartement est servi

address.unit_number apparaît dans le détail d'un bien. Il porte le numéro d'appartement ou d'unité quand il est connu, sinon null.
// v3.1
"address": {
  "street_number": "3095",
  "street_name":   "Avenue Ernest-Hemingway",
  "unit_number":   "107",
  "…":             "…"
}
À faire : rien d'obligatoire. Si votre désérialisation refuse les champs inconnus, déclarez ce champ avant de changer de préfixe.

Aménagements : l'alias amenties disparaît

Les résultats de recherche servaient les aménagements deux fois, sous amenities et sous l'alias mal orthographié amenties. La 3.1 ne sert plus que amenities, au contenu identique.
À faire : lire amenities.

Marche à suivre

  1. Vérifier votre désérialisation sur les quatre points ci-dessus, en particulier si elle est typée strictement : les surfaces formatées deviennent des objets, les montants du viager des nombres, et un champ apparaît dans l'adresse.
  2. Tester sur /api/v3.1/ avec vos clés habituelles. Les mêmes clés apiKey et apiToken servent les deux préfixes, sur les mêmes boards : vous pouvez appeler la 3.1 en parallèle de votre production sans rien demander, et comparer les deux réponses côte à côte.
  3. Contrôler l'en-tête X-Api-Version de vos réponses : il vaut 3.1 sur le nouveau préfixe et 3.0 sur l'ancien. C'est le moyen le plus sûr de savoir quel format vous recevez.
  4. Basculer le préfixe dans votre configuration. Aucune autre modification d'URL n'est nécessaire : les routes sont identiques.
# avant
GET https://app.mls-connect.com/fr/api/v3/properties/search?mls_board=xxx

# après
GET https://app.mls-connect.com/fr/api/v3.1/properties/search?mls_board=xxx

Ce qui ne change pas

  • Les routes, leurs paramètres et leurs filtres
  • L'authentification par apiKey et apiToken, et les droits par board
  • La pagination et les curseurs
  • Le format d'écriture des biens, agences, utilisateurs et passerelles : un même payload s'envoie indifféremment sur les deux préfixes
  • Les codes HTTP et le format des erreurs

Fin de support de la 3.0

Aucune date n'est fixée. Quand elle le sera, elle sera annoncée ici et dans les réponses de /api/v3/ par les en-têtes standards Deprecation: true et Sunset: <date>, pour que vos propres journaux puissent vous alerter.