1) Récupérer les annonces actives

/api/search

Cette route renvoie la liste des annonces qui sont activées sur le site flatbay.fr
Elle ne necessite pas d'authentification puisque ces données sont de toute façon publique.
ps: Cette page permet d'obtenir les mêmes résultats et donc de se familiariser avec les données https://flatbay.fr/fr/search

La pagination par defaut est à 1000.

Il est possible de transmettre les paramètres suivants pour filtrer les résultats :

"rentsellType" avec la valeur property.rentsellType.rent pour les locations ou property.rentsellType.sell pour les ventes
"page" avec un nombre, afin de charger la page de resultat souhaitée.
"etablissementId" avec un nombre, afin de ne voir que les annonces de l'etablissement correspondant.
"search" avec une string, afin de filtrer parmis adresse / ville / code postal / id / numero de lot.
"distance" avec un nombre en kilometre, afin de ne voir que les biens suffisamment proches (il est necessaire de fournir la latitude et la longitude).
"lat" permet de spécifier la latitude
"lng" permet de spécifier la longitude

Exemple :

/api/search?etablissementId=1

/api/search?lat=48.8257157&lng=2.2935099&distance=2

Exemple de reponse :

{
    "page": 0,
    "nbbypage": 100,
    "nb": 220,
    "properties": [
        {
            "id": 2427,
            "name": "Rue Saint-Jacques Paris 75005",
            "userId": 113204,
            "address": "260 Rue Saint-Jacques",
            "cp": "75005",
            "city": "Paris",
            "lat": "48.8426268",
            "description": "🏡 Appartement prêt à vivre\r\n\r\n👌 Entièrement équipé (lave-linge, lave-vaisselle, micro-ondes, four,       plaques, grille-pain, vaisselle, aspirateur, TV...)\r\n🛏 Les chambres sont toutes équipées d'un lit double ou King size et       possèdent un bureau et de nombreux rangements\r\n\r\n👍 Pièces communes :\r\n- Entrée\r\n- Séjour donnant sur un balcon filant       avec table et chaises\r\n- Cuisine séparée + coin repas\r\n- Salle de douche séparée + WC\r\n- Salle de bain séparée\r\n- WC       séparé\r\n\r\n🚆 Transports : \r\nRER B PORT ROYAL ou LUXEMBOURG (à 450m)\r\nLigne 7 Place Monge (Jardin des Plantes) (à 810m)      \r\nLigne 6 Raspail (à 868m)\r\nLigne 10 Cardinal-Lemoine (à 878m)\r\nLigne 4 Vavin (à 897m)\r\nLigne 12 Notre-Dame des Champs       (à 956m)\r\n\r\n🛒 Commerces à proximité :\r\nSupérette au pied de l'immeuble, \r\nBoulangerie en face \r\nSupermarché à moins       de 4 min. à pieds\r\n\r\n😊 Vous n'avez plus qu'à déposer vos valises\r\n👩‍💻 Idéal pour jeunes actifs /       étudiants\r\n\r\n\r\n⚡️Inclus dans les charges :\r\n✅ Charges immeuble\r\n✅ Eau froide\r\n✅ Eau Chaude\r\n✅ Chauffage\r\n✅       Électricité\r\n✅ Internet\r\n✅ Ménage\r\n✅ Taxe ordure ménagères\r\n\r\n💸Aide au logement OK",
            "surface": 152.47,
            "ascenseur": 1,
            "meuble": 1,
            "balcon": 1,
            "nbFree": 1,
            "createdAt": "2021-03-12T16:56:21.000Z",
            "updatedAt": "2022-07-13T14:11:57.000Z",
            "country": "France",
            "lng": "2.341097099999999",
            "type": "property.type.appart",
            "etage": 5,
            "nbRoom": 5,
            "nbDouche": 2,
            "nbWc": 2,
            "loyer": 4800,
            "depot": 6384,
            "charge": 600,
            "chargesType": "provision",
            "chauffage": 1,
            "electricite": 1,
            "coloc": 1,
            "start": null,
            "startRoom": 1,
            "embed": "https://envisite.net/vtour/fr/49guvk/frame",
            "percent": 100,
            "nbPiece": 6,
            "gardien": 1,
            "internet": 1,
            "terrasse": 0,
            "parking": 0,
            "cave": 0,
            "dpe": 212,
            "lot": "M97",
            "public": "2022-05-30T22:00:00.000Z",
            "phone": "06 68 53 12 15",
            "email": "hello@flatnyou.com",
            "colocOnly": 1,
            "ges": 49,
            "jardin": 0,
            "showPhone": 1,
            "minLoyer": 890,
            "minCharge": 120,
            "etablissementId": 1,
            "frais": 1795,
            "fraisRoom": 359,
            "pinel": 0,
            "metro": "[{\"station\":\"LUXEMBOURG\",\"type\":\"rail\",\"ligne\":\"B\",\"coordinates\":[2.340564,48.847012],      \"distance\":\"490\"},{\"station\":\"PORT ROYAL\",\"type\":\"rail\",\"ligne\":\"B\",\"coordinates\":[2.336669,48.839831],      \"distance\":\"450\"},{\"station\":\"Cluny-La Sorbonne\",\"type\":\"metro\",\"ligne\":\"10\",\"coordinates\":[2.345049,48.      850799],\"distance\":\"954\"},{\"station\":\"Maubert-Mutualité\",\"type\":\"metro\",\"ligne\":\"10\",\"coordinates\":[2.348944,      48.84972],\"distance\":\"976\"},{\"station\":\"Cardinal-Lemoine\",\"type\":\"metro\",\"ligne\":\"10\",\"coordinates\":[2.351354,      48.846709],\"distance\":\"878\"},{\"station\":\"Notre-Dame des Champs\",\"type\":\"metro\",\"ligne\":\"12\",\"coordinates\":[2.      328463,48.844786],\"distance\":\"956\"},{\"station\":\"Vavin\",\"type\":\"metro\",\"ligne\":\"4\",\"coordinates\":[2.328885,48.      842063],\"distance\":\"897\"},{\"station\":\"Raspail\",\"type\":\"metro\",\"ligne\":\"6\",\"coordinates\":[2.330697,48.838881],      \"distance\":\"868\"},{\"station\":\"Place Monge (Jardin des Plantes)\",\"type\":\"metro\",\"ligne\":\"7\",\"coordinates\":[2.      352129,48.843167],\"distance\":\"810\"},{\"station\":\"Censier-Daubenton\",\"type\":\"metro\",\"ligne\":\"7\",\"coordinates\":[2.      351774,48.840597],\"distance\":\"814\"}]",
            "askVisite": 0,
            "eauchaude": 1,
            "eaufroide": 1,
            "entretien": 1,
            "eautype": "property.production.individuelGaz",
            "chauffagetype": "property.production.individuelGaz",
            "velo": 0,
            "flatsy": 0,
            "flatsyId": null,
            "flatsyStaffed": 0,
            "nbEtage": 6,
            "keyInfo": null,
            "keyDate": null,
            "ubiflow": 1,
            "tenantPhone": null,
            "flatsyAgentName": null,
            "flatsyAgentPhone": null,
            "minDepot": 1200,
            "periclesId": null,
            "rentsellType": "property.rentsellType.rent",
            "fraisType": null,
            "prix": null,
            "foncier": null,
            "flatsyAgentPicture": null,
            "seloger": 1,
            "video": 0,
            "facebook_mp_rentals": 0,
            "lacartedescolocs": 1,
            "leboncoin_immo": 1,
            "vitrine_media": 1,
            "lbc_aval": 1,
            "desactivateAlertAt": null,
            "flatsyKey": 0,
            "landlordPhone": null,
            "tenantDispo": null,
            "tenantName": null,
            "landlordName": null,
            "flatsyDisable": 0,
            "flatsyAutoAccept": 0,
            "entretienJardin": 0,
            "entretienChaudiere": 1,
            "ordures": 1,
            "menage": 1,
            "risque": 0,
            "bailType": "property.bailType.collectif",
            "box": 0,
            "piscine": 0,
            "sport": 0,
            "cinema": 0,
            "type2": "property.type2.co",
            "construction": "property.construction.1946",
            "tenantDispoEnd": null,
            "gli": 0,
            "zoneId": null,
            "checkandvisitId": "ppy_5FyQqW",
            "maxLoyer": 890,
            "maxCharge": 120,
            "maxDepot": 1200,
            "digicode": "Vigik",
            "batiment": null,
            "escalier": "5",
            "porte": null,
            "compteurElec": null,
            "compteurElecId": null,
            "compteurGaz": null,
            "compteurEauChaude": null,
            "compteurEauFroide": null,
            "compteurThermique": null,
            "caveLocation": null,
            "parkingLocation": null,
            "archive": 0,
            "plaque": 1,
            "four": 1,
            "microonde": 1,
            "frigo": 1,
            "laveLinge": 1,
            "secheLinge": 0,
            "laveVaisselle": 1,
            "cafetiere": 0,
            "tv": 1,
            "dbOpen": null,
            "dbClose": null,
            "hauteur": null,
            "exposition": null,
            "traversant": 0,
            "fibre": 0,
            "jacuzzi": 0,
            "hammam": 0,
            "sauna": 0,
            "clim": 0,
            "travaux": 0,
            "ravalementDate": null,
            "refectionDate": null,
            "travauxDesc": null,
            "vitrage": "property.vitrage.double",
            "grillePain": 1,
            "aspirateur": 1,
            "bouilloire": 1,
            "hotte": 1,
            "vaisselle": 1,
            "linge": 1,
            "arriveeEau": null,
            "boxLocation": null,
            "refectionCommuneDate": null,
            "codeWifi": "Wood2013!",
            "disjoncteur": null,
            "boiteAuxLettres": null,
            "logic_immo": 1,
            "poubelles": null,
            "bailDuration": "property.bailDuration.1year",
            "terrainUsage": null,
            "terrainViable": 0,
            "nbLots": 1,
            "pmr": 0,
            "longueur": null,
            "largeur": 0,
            "sousSol": 0,
            "vitrine": 0,
            "cuisine": 0,
            "publicEnd": null,
            "bailRight": 0,
            "koliving": 0,
            "wizi": 0,
            "insoon_eb": 0,
            "commentLocation": null,
            "miloctav": 0,
            "encadrement": 0,
            "encadrementMax": null,
            "encadrementMaxm": null,
            "occupe": 0,
            "nbLotsCoproperty": null,
            "courtProceeding": 0,
            "groupeId": null,
            "prospect": null,
            "extraction": null,
            "miseEnLoc": null,
            "livraison": null,
            "needMeuble": null,
            "loyerSouhaite": null,
            "explorimmo_v2": 0,
            "horiz_io": 0,
            "immostreet": 0,
            "fnaim": 0,
            "settlesweet": 0,
            "superimmo": 0,
            "ouestfrance": 0,
            "loyerIdea": null,
            "dejaLoue": null,
            "surfaceJardin": null,
            "surfaceTerrain": null,
            "surfaceTerrasse": null,
            "surfaceBalcon": null,
            "etatGeneral": null,
            "parkingNumber": null,
            "garageNumber": null,
            "valuationValue": null,
            "valuationRangeLower": null,
            "valuationRangeUpper": null,
            "valuationConfidence": null,
            "flatsyStart": null,
            "infoColoc": null,
            "jinka": 1,
            "meilleursagents": 1,
            <!-- "meilleursagentsvendu": 1, -->
            "etreproprio": 1,
            "embed2": null,
            "favori": 0,
            "etablissementName": "FlatnYou",
            "roomId": 1990,
            "roomName": "2",
            "roomLoyer": 890,
            "roomCharge": 120,
            "roomDepot": 1200,
            "roomStart": "2022-07-31T22:00:00.000Z",
            "distance": 1.671663502398682
        },
        ...
    ]
}

2) recuperer toutes les informations d'une propriété

/api/property/:id?apiKey=xxxxx

il faudra que l'equipe flatbay vous fournisse une clé d'api pour utiliser cette route.

3) Extractions des leads

Cette url renvoie les leads du groupe dans un tableau en json : Un resultat par lead.

Par defaut cela renvoie uniquement les leads créés ou mis à jour durant les dernieres 24H.

Etant donné le caractere hautement confidentiel de ces données il faudra que l'equipe flatbay vous fournisse une clé d'api pour utiliser cette route.

/api/candidates?apiKey=xxxxx

Pour cibler une autre période, utiliser les paramètres start et end (dates ISO 8601). La fenêtre end - start est plafonnée à 31 jours (1 mois) ; au-delà l'API renvoie 400 RANGE_TOO_LARGE. Pour un historique plus long, itérer par tranches.

/api/candidates?apiKey=xxxxx&start=2025-01-01&end=2025-01-31

Le paramètre from={date} reste accepté en alias de start (avec end = maintenant) mais est déprécié :

/api/candidates?apiKey=xxxxx&from=2025-04-15T12:00:00

Pour identifier un appelant, phone renvoie toutes les candidatures dont un colocataire porte ce numéro, sans fenêtre de dates (formats 06…, +336…, 336… acceptés) :

/api/candidates?apiKey=xxxxx&phone=0612345678

La clé se passe toujours en paramètre d'URL ?apiKey= : un header n'est pas lu.

Chaque candidature expose ses colocataires (users[]) et, pour chacun, ses garants (users[].garants[]) avec leurs documents. Le détail /api/candidate/:id expose en plus les notes (comments[]).

Créer des contacts sans bien

POST /api/contacts/create/:etablissementId?apiKey=xxxxx
Content-Type: application/json
{ "users": [{ "email": "jean.dupont@exemple.fr", "firstName": "Jean", "lastName": "Dupont", "phone": "0612345678", "rentsellType": "property.rentsellType.rent", "optin": "1" }] }

Crée des contacts en recherche, rattachés au groupe et au répertoire de l'agence, sans candidature sur un bien. Mêmes champs que la création de candidatures, plus rentsellType facultatif (property.rentsellType.rent, .sell ou .both). 50 contacts au maximum par appel ; un email déjà connu réutilise le contact existant sans le modifier. Réponse { "status": "ok", "errors": [...], "users": [{ "id": 123, "email": "…" }] }.

Modifier une candidature

POST /api/candidate/:id?apiKey=xxxxx&status=candidate.status.xxx&lostReason=xxx&archive=0|1

Ajouter une note sur une candidature

POST /api/candidate/:id/comment?apiKey=xxxxx
Content-Type: application/json
{ "authorEmail": "agent@exemple.fr", "comment": "texte de la note" }

authorEmail doit être l'email d'un agent de l'établissement de la candidature (cf. commerciaux[].email) : c'est lui qui signe la note. Réponse { "status": "ok", "id": <id de la note> }.

Un compte rendu d'appel passe par la même route, avec un objet call à la place (ou en plus) de comment :

{
    "authorEmail": "agent@exemple.fr",
    "call": {
        "calledAt": "2026-09-04T14:27:00+02:00",
        "direction": "in",
        "result": "Qualifié",
        "summary": "résumé de l'échange",
        "qualification": { "situation": "CDI", "revenus": 2500 },
        "visitWish": "samedi matin",
        "toConfirm": "garant à confirmer",
        "needCallback": true
    }
}

calledAt (ISO 8601) et direction (in ou out) sont obligatoires, le reste est facultatif ; qualification accepte un texte ou un objet. needCallback: true marque la note comme importante pour l'agence.

Webhook

Sur demande, flatbay configure une URL de webhook au niveau du groupe (groupe.apiHook). Chaque événement de candidature (candidate_create, candidate_status, candidate_cancel…) ou de visite (visite_*) y est envoyé en POST JSON, avec le header X-Flatbay-Token égal à la clé API du groupe. Un endpoint qui ne répond pas en 2xx n'est pas rejoué : les candidatures modifiées restent récupérables via /api/candidates?start=…&end=….

4) Extractions des visites

Cette url renvoie les visites du groupe dans un tableau en json : Un resultat par visite.

Par defaut cela renvoie uniquement les visites créés ou mis à jour durant les dernieres 24H.

Etant donné le caractere hautement confidentiel de ces données il faudra que l'equipe flatbay vous fournisse une clé d'api pour utiliser cette route.

/api/visites?apiKey=xxxxx

Mêmes règles que pour /api/candidates : paramètres start et end, fenêtre max 31 jours, from déprécié.

/api/visites?apiKey=xxxxx&start=2025-01-01&end=2025-01-31

5) importer des biens sur flatbay

Vous pouvez nous fournir un flux au format ubiflow :
Concrêtement c'est un fichier xml, disponible sur une url publique, que notre serveur appellera toutes les 6H.

Voici un document PDF décrivant le cahier des charges (cf. "Format Integration Standard Immo ancien XML - UBIFLOW.pdf")
https://drive.google.com/file/d/0B0iuff2wbgOudVpHN0RNQnlpU0E/view?usp=sharing&resourcekey=0-0W9CpMSe-6Vn4Wt5cibB6g

Un document CSV décrivant les données d'une annonce (cf."Dictionnaire_donnees_immobilier.csv" )
https://drive.google.com/file/d/0B0iuff2wbgOuejhIbTRCUHR6Vnc/view?usp=sharing&resourcekey=0-ab-4MDcQ5vzZKC3rpfTHmQ

Exemple de fichier zip : https://drive.google.com/file/d/0B0iuff2wbgOuVzNyaXVLQXFGS1k/view?resourcekey=0-IEYYIwXkYisWAedG63fxVA

Exemple de xml :

<client>
    <annonce>
        <reference>76default</reference>
        <colocation>1</colocation>
        <titre>
            <![CDATA[ 1 chambre disponible en colocation ]]>
        </titre>
        <texte>
            <![CDATA[ COLOCATION 1 Chambre disponible CHAMBRE 3 (à titre indicatif) Loyer HC :€ / mois Charges : 26.67 € / mois Disponibilité : le 11/10/2022 Bienvenue dans une grande maison ! Fin de bail le 28/02/2023 Remise de 50% sur les frais d'agence Entièrement équipé (lave-linge, lave-vaisselle, micro-ondes, grille-pain, four, plaques, vaisselle, aspirateur, TV....) 🛏 Les chambres sont toutes équipées d'un lit double et possèdent de nombreux rangements Pièces communes : Grand salon avec cuisine ouverte Une salle de douche Une salle de douche privée chambre RDC Terrasse Commerces à proximité Vous n'avez plus qu'à déposer vos valises Idéal pour jeunes actifs / étudiants ️ Inclus dans les charges : charges entretien espaces extérieurs propriété, eau froide, taxe ordure ménagères. ️Estimation consommables (internet, Gaz & électricité) : Prévoir + 45 €/chambre/mois Aide au logement OK Frais d'agence pour tout le logement : 289 € Charges pour tout le logement : 80.01 € Dépôt de garantie pour tout le logement :€ ]]>
        </texte>
        <date_saisie>12/09/2022</date_saisie>
        <contact_a_afficher>Contact</contact_a_afficher>
        <charges_avec_chauffage>0</charges_avec_chauffage>
        <charges_avec_eau_chaude>0</charges_avec_eau_chaude>
        <meuble>1</meuble>
        <email_a_afficher>flatnyou@bot.flatbay.fr</email_a_afficher>
        <telephone_a_afficher>0668531215</telephone_a_afficher>
        <url_annonce_sur_site_annonceur>https://flatbay.fr/fr/property/show/76</url_annonce_sur_site_annonceur>
        <photos>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/1935 ]]>
            </photo>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/1936 ]]>
            </photo>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/1937 ]]>
            </photo>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/43872 ]]>
            </photo>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/43873 ]]>
            </photo>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/43875 ]]>
            </photo>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/43876 ]]>
            </photo>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/1944 ]]>
            </photo>
            <photo>
                <![CDATA[ https://flatbay.fr/fr/document/picture/1945 ]]>
            </photo>
        </photos>
        <bien>
            <code_type>1100</code_type>
            <adresse>
                <![CDATA[ 33 Rue de Fleury ]]>
            </adresse>
            <code_postal>
                <![CDATA[ 92140 ]]>
            </code_postal>
            <ville>
                <![CDATA[ Clamart ]]>
            </ville>
            <surface>78</surface>
            <nb_pieces_logement>4</nb_pieces_logement>
            <nombre_de_chambres>3</nombre_de_chambres>
            <nb_salles_de_bain>2</nb_salles_de_bain>
            <nb_wc>2</nb_wc>
            <etage>0</etage>
            <latitude>48.8133601</latitude>
            <longitude>2.267400899999984</longitude>
            <diagnostiques>
                <dpe_etiquette_ges>A</dpe_etiquette_ges>
                <dpe_valeur_ges>0</dpe_valeur_ges>
                <dpe_etiquette_conso>D</dpe_etiquette_conso>
                <dpe_valeur_conso>230</dpe_valeur_conso>
            </diagnostiques>
        </bien>
        <prestation>
            <type>L</type>
            <loyer>586</loyer>
            <charges>27</charges>
            <depot_garantie>735</depot_garantie>
            <frais_agence>289</frais_agence>
            <modalites_recuperation_charges_locatives>provision annuelle</modalites_recuperation_charges_locatives>
            <loyer_mensuel_cc>613</loyer_mensuel_cc>
            <honoraires_etat_des_lieux>0</honoraires_etat_des_lieux>
        </prestation>
        <afficher_telephone>1</afficher_telephone>
        <afficher_prix>1</afficher_prix>
        <url_tarifs_publics>https://www.flatnyou.com/gestion-colocation</url_tarifs_publics>
        <afficher_url_annonceur>1</afficher_url_annonceur>
        <prix_vendu_fai>289</prix_vendu_fai>
        <honoraires_negociation>0</honoraires_negociation>
        <prix_est_fai>1</prix_est_fai>
        <prix_signature>289</prix_signature>
        <duree_du_bail>12</duree_du_bail>
        <climatise>0</climatise>
        <hauteur_plafond/>
        <jacuzzi>0</jacuzzi>
        <acces_handicapes>0</acces_handicapes>
        <surface_carrez>78</surface_carrez>
        <nb_caves>0</nb_caves>
        <chauffage_type>individuel</chauffage_type>
        <chauffage_energie>électricité</chauffage_energie>
        <tv>1</tv>
        <nb_garages>0</nb_garages>
        <nb_parkings>0</nb_parkings>
        <sous_sol>0</sous_sol>
        <eau_chaude_distribution>ballon électrique</eau_chaude_distribution>
        <bien_avec_chauffage>1</bien_avec_chauffage>
        <bien_avec_eau_chaude>1</bien_avec_eau_chaude>
        <alur_syndic_en_procedure>0</alur_syndic_en_procedure>
        <acces_wifi>1</acces_wifi>
        <nb_wc_independants>2</nb_wc_independants>
        <nb_chambres_dispo>1</nb_chambres_dispo>
        <code_postal_reel>92140</code_postal_reel>
        <pays>France</pays>
        <ville_reelle>Clamart</ville_reelle>
        <surface_logement>78</surface_logement>
        <surface_commerciale>78</surface_commerciale>
        <surface_activite>78</surface_activite>
        <loyer_mensuel>586</loyer_mensuel>
        <charges_locatives>27</charges_locatives>
        <honoraires_location>289</honoraires_location>
        <equipe_four>1</equipe_four>
        <equipe_microondes>1</equipe_microondes>
        <equipe_frigo>1</equipe_frigo>
        <equipe_lave_vaisselle>1</equipe_lave_vaisselle>
        <equipe_grille_pain>1</equipe_grille_pain>
        <equipe_cafetiere>1</equipe_cafetiere>
        <equipe_plaque_cuisson>1</equipe_plaque_cuisson>
        <equipe_vaisselle>1</equipe_vaisselle>
        <avec_linge_maison>1</avec_linge_maison>
        <equipe_lave_linge>1</equipe_lave_linge>
        <copropriete>1</copropriete>
        <terrasse>1</terrasse>
        <cuisine_equipee>1</cuisine_equipee>
        <commentaires_proche_transports>
            <![CDATA[ N CLAMART à 418 mètres, C ISSY à 952 mètres, ]]>
        </commentaires_proche_transports>
    </annonce>
</client>

6) sso

Le but est qu'une agence immobilière cliente de flatbay puisse connecter ses utilisateurs sans passer par un formulaire de connection sur flatbay.fr

Nous fournissons une API afin qu'il soit possible d'inscrire et connecter vos utilisateurs

En pratique il suffit de transmettre l'url fournie par flatbay à l'utilisteur et il sera connecté automatiquement.

L'utilisateur (agent immobilier) est connecté sur l'intranet de l'agence correspondante.
il clique sur un bouton pour se connecter à flatbay.
le serveur va alors appeller l'api de flatbay afin de récupérer une url de connection.
le serveur transmet l'url à l'utilisateur
l'utilisateur est connecté à flatbay

PS: la clé doit rester securisée car en pratique elle permet d'être connecté en tant que n'importe quel agent de l'agence ou de se créer un compte.

    curl https://flatbay.fr/fr/api/sso?key=xxxxxx&email=xxxxxxx
    {
        url: https://flatbay.fr/fr/......
    }

Le token de connection dans l'url recu est valable 1 jour, mais s'auto détruit des qu'il est utilisé.

7) récupérer un bail (Document_editor)

À partir de l'identifiant d'un document (un bail ou un acte de cautionnement généré via l'éditeur de documents), cette route renvoie toutes les données du bail en JSON : le bien / lot, les intervenants (agent, bailleurs, locataires, garants) avec leur identifiant flatbay et leur rôle, les mandats de prélèvement SEPA, les variables du document, la TVA appliquée au loyer et aux charges, le statut, les annexes, et les URL de téléchargement du PDF signé, des annexes et des RIB des locataires.

Il faudra que l'equipe flatbay vous fournisse une clé d'api (au niveau du groupe) pour utiliser ces routes.

/api/document/:id?apiKey=xxxxx

Réponse (extrait) :

{
  "document": {
    "id": 12345,
    "type": "document.type.bailhabitationmandataire",
    "typeSlug": "bail-habitation-mandataire",
    "typeLabel": "Bail d'habitation (bailleur représenté par le mandataire)",
    "name": "Bail_habitation_Dupont.pdf",
    "status": "signed",
    "statusLabel": "Signé par toutes les parties",
    "generated": true,
    "draft": false,
    "createdAt": "2026-07-13T09:57:16+02:00",
    "updatedAt": "2026-07-13T10:00:57+02:00",
    "nbPages": 6,
    "size": 200674,
    "extension": "pdf",
    "signature": { "provider": "yousign", "procedureId": "…", "signed": true, "signedAt": "2026-07-14T10:00:00+02:00" },
    "lease": { "locName": "…", "bailName": "…", "rentAmountNumber": "…", "chargeAmountNumber": "…", "duration": "…", "cautionName": "…" },
    "tva": {
      "loyer":   { "assujetti": true,  "taux": 10,   "montantHt": 850, "montantTva": 85,   "montantTtc": 935 },
      "charges": { "assujetti": false, "taux": null, "montantHt": 60,  "montantTva": null, "montantTtc": null }
    },
    "fieldValues": { "loyerMensuel": "…", "depotGarantie": "…", "…": "toutes les variables du document" }
  },
  "property": { "id": 2427, "type": "…", "address": "…", "cp": "…", "city": "…", "lots": [ … ], "room": null, "rooms": [] },
  "etablissement": { "id": 1, "name": "…", "address": "…", "siret": "…" },
  "intervenants": {
    "agent":      { "flatbayId": 113204, "civility": "…", "firstName": "…", "lastName": "…", "email": "…", "phone": "…" },
    "bailleurs":  [ { "flatbayId": "42", "qualite": "proprietaire.qualite.physique", "firstName": "…", "lastName": "…", "email": "…", "representants": [ { "flatbayId": "31379", "firstName": "…", "quality": "…", "isReferent": false } ] } ],
    "locataires": [ { "flatbayId": "77", "civility": "…", "firstName": "…", "lastName": "…", "email": "…", "phone": "…", "ribs": [ { "id": 98123, "name": "rib.pdf", "fileUrl": "https://…/api/document/12345/ribs/98123/file?apiKey=xxxxx" } ] } ],
    "garants":    [ { "flatbayId": "…", "firstName": "…", "lastName": "…", "email": "…" } ]
  },
  "mandatsSepa": [ { "flatbayId": "…", "rum": "25092026002", "type": "recurrent", "jourPrelevement": 5, "locataireFlatbayId": "77", "creancier": { … }, "payeur": { …, "iban": "FR76…" } } ],
  "annexes": [ { "id": 55, "name": "Assurance.pdf", "fileType": "application/pdf", "fileUrl": "https://…/api/document/12345/annexes/55/file?apiKey=xxxxx" } ],
  "pdf": { "available": true, "url": "https://…/api/document/12345/pdf?apiKey=xxxxx" }
}

intervenants — les parties réellement présentes sur le bail, telles que figées au moment de la génération (et non l'ensemble des locataires / bailleurs rattachés au bien).

agent : le gestionnaire flatbay qui a produit le document.
bailleurs, locataires, garants : les parties groupées par rôle. garants n'est renseigné que pour les baux qui portent des entités garant ; pour l'acte de cautionnement, les informations de la caution sont dans document.lease.caution* et document.fieldValues.
flatbayId : identifiant flatbay de la partie — proprietaire pour un bailleur, locataire pour un locataire, user pour un représentant, l'agent ou un garant. Il vaut l'identifiant CRM lorsque la partie a été choisie depuis le carnet d'adresses flatbay, et un identifiant local si elle a été saisie manuellement dans l'éditeur.
locataires[].ribs : les RIB du locataire. Contrairement au reste du bloc, ils sont lus en direct dans le CRM (pièces justificatives du locataire) et non figés à la génération — ils reflètent donc l'état courant du dossier. Toujours présent, éventuellement vide. Trois cas donnent une liste vide :
- le document n'a pas été produit par l'éditeur de documents (bail historique simplement téléversé) ;
- le locataire a été saisi manuellement dans l'éditeur : il n'est rattaché à aucune fiche CRM ;
- le locataire n'a tout simplement pas déposé de RIB.
Les fichiers sont servis en JPEG (toute pièce jointe est convertie à l'upload) : un RIB fourni en PDF de plusieurs pages produit une entrée par page, toutes de même name, ordonnées par id croissant.

property.room / property.rooms — colocation. Deux formes de bail, deux champs :

bail individuel de colocation (un bail par chambre) : property.room porte la chambre louée, property.rooms vaut [] ;
bail collectif de colocation (un seul bail pour toutes les chambres) : property.room vaut null, property.rooms porte le détail par chambre — la clé de répartition convenue entre les colocataires, imprimée dans le bail sous le titre « Quotes-parts ».

property.rooms vaut [] sur tout autre type de bail. Les montants sont ceux figés à la génération : ils ont pu être corrigés depuis sur la fiche du bien, c'est le bail signé qui fait foi. loyerCc (loyer + charges) et quotePartLoyerCc (part du loyer charges comprises du bail, en %) en sont dérivés ; la somme des quotes-parts peut ne pas retomber exactement sur 100 après arrondi au centième.

"rooms": [
  { "id": 7, "name": "1", "loyer": 420, "charge": 30, "depot": 420, "loyerCc": 450, "quotePartLoyerCc": 52.63 },
  { "id": 8, "name": "2", "loyer": 380, "charge": 25, "depot": 380, "loyerCc": 405, "quotePartLoyerCc": 47.37 }
]

mandatsSepa — les mandats de prélèvement SEPA signés avec le bail, chacun imprimé sur ses propres pages du PDF. Toujours présent, [] si le bail n'en porte pas. Un mandat de prélèvement SEPA seul (typeSlug = mandat-prelevement-sepa) est servi par la même route, avec le même bloc.

"mandatsSepa": [
  {
    "flatbayId": "ea094429-22e0-4d4f-b3ff-4723f9144cd5",
    "rum": "25092026002",
    "type": "recurrent",
    "jourPrelevement": 5,
    "datePrelevement": null,
    "locataireFlatbayId": "77",
    "creancier": {
      "source": "mandataire", "bailleurFlatbayId": null, "ics": "FR37ZZZ852D76",
      "type": "morale", "civility": null, "firstName": null, "lastName": null,
      "companyName": "Agence du Port", "legalForm": "SAS",
      "address": "1 quai Ouest", "cp": "29200", "city": "Brest"
    },
    "payeur": {
      "type": "physique", "civility": "user.civility.m", "firstName": "Jean", "lastName": "Dupont",
      "companyName": null, "representant": null,
      "address": "2 rue Haute", "cp": "29200", "city": "Brest", "country": "France",
      "iban": "FR7630006000011234567890189"
    }
  }
]

flatbayId : identifiant du mandat, stable d'une regénération à l'autre — la clé de dédoublonnage.
rum : référence unique du mandat (JJMMAAAA + numéro d'ordre du jour sur trois chiffres), unique par ICS. Elle est attribuée à la génération définitive et vaut null avant : un mandat sans RUM n'est pas utilisable. Un mandat n'est valable qu'une fois signé — se fier à document.signature.signed (ou document.status = signed) avant de prélever.
type : recurrent (prélèvement mensuel, au jour jourPrelevement, de 1 à 31) ou ponctuel (prélèvement unique, à la date datePrelevement, au format AAAA-MM-JJ). La valeur qui ne s'applique pas vaut null.
locataireFlatbayId : le locataire pour qui le mandat est signé, même quand le payeur est un tiers (un parent, une société). Dans un bail, c'est le flatbayId d'un des intervenants.locataires ; pour un mandat seul, l'identifiant de la fiche locataire. null si le locataire n'est plus une partie du document.
creancier.source : mandataire (l'établissement du bloc etablissement, dont l'ICS est celui de sa fiche), bailleur (bailleurFlatbayId désigne alors un des intervenants.bailleurs, ou la fiche propriétaire pour un mandat seul ; null si ce bailleur n'est plus une partie) ou null (créancier saisi à la main).
creancier.type / payeur.type : physique ou morale. Toutes les clés sont présentes ; celles qui ne concernent pas le type valent null (firstName d'une société, companyName d'une personne). payeur.representant (firstName, lastName, quality) n'est renseigné que pour un payeur personne morale. civility suit les codes des autres parties (user.civility.m, user.civility.mme…).
creancier.ics et payeur.iban ne sont publiés que valides — null sur un brouillon en cours de saisie. L'IBAN est au format électronique (sans espaces), celui d'un fichier de prélèvement.

document.lease : sous-ensemble stable des données du bail (montants, dates, caution) figé à la génération. Attention : rentAmountNumber / rentAmountLetter / chargeAmountNumber / chargeAmountLetter sont des montants hors taxes, et ne sont renseignés que pour l'acte de cautionnement — ils valent null sur un bail (utiliser document.tva.*.montantHt, ou document.fieldValues.loyerMensuel / chargesAmount).

document.tva : TVA appliquée au loyer et aux charges. Vaut null pour les types de baux qui ne gèrent pas la TVA (aujourd'hui seuls les baux résidence étudiante la portent) et pour l'acte de cautionnement. montantHt est le montant saisi par l'agent (hors taxes) ; taux (en %), montantTva et montantTtc en sont dérivés et valent null quand la ligne n'est pas assujettie. Tous les montants sont des nombres, null si non renseignés.

document.fieldValues : toutes les variables du document. Contrairement aux blocs ci-dessus, ce n'est pas un contrat stable — les identifiants de variables diffèrent selon le type de document et peuvent évoluer.

Statut (document.status) — valeurs possibles :

code	signification
`draft`	brouillon / en rédaction
`generated`	généré, pas encore envoyé en signature
`pending_signature`	en cours de signature
`signed`	signé par toutes les parties (le PDF final fusionné est disponible)
`unknown`	indéterminé

Limites connues :

flatbay ne distingue pas « signé par toutes les parties » et « document final signé » : le PDF final est disponible dès que status = signed.
l'état « signature annulée » n'est pas persistant : annuler une signature supprime le document, qui devient alors introuvable via l'API (404). L'annulation sera notifiée par webhook (à venir).
pour un brouillon (draft) dont les parties n'ont pas encore été enregistrées, intervenants.bailleurs/locataires/garants peuvent être vides.

Codes d'erreur : 403 NOAPIKEY (clé absente), 403 BADGROUPE (document d'un autre groupe), 400 BADDOCUMENTTYPE (l'id n'est pas un bail/acte éditable), 404 (document introuvable ou supprimé).

Téléchargement du bail signé (PDF final, document principal + annexes fusionnées) :

/api/document/:id/pdf?apiKey=xxxxx

Téléchargement d'une annexe (l'annexeId provient du champ annexes[].id ou de l'URL annexes[].fileUrl) :

/api/document/:id/annexes/:annexeId/file?apiKey=xxxxx

Téléchargement du RIB d'un locataire (le ribId provient du champ intervenants.locataires[].ribs[].id ou de l'URL ribs[].fileUrl) :

/api/document/:id/ribs/:ribId/file?apiKey=xxxxx

8) récupérer les pièces justificatives d'un utilisateur

Cette route liste les pièces justificatives d'un utilisateur — locataire ou garant — à partir de son identifiant flatbay, indépendamment de toute candidature. Elle complète /api/candidates, qui ne les expose qu'imbriquées dans une candidature.

Il faudra que l'equipe flatbay vous fournisse une clé d'api (au niveau du groupe) pour utiliser ces routes.

/api/user/:userId/documents?apiKey=xxxxx

Réponse :

[
    {
        "documentId": 57187226,
        "name": "Bulletins de paie 2026-04.pdf",
        "type": "document.type.salaire",
        "nbPages": 2,
        "size": 531092,
        "pageIds": [57187226, 57187227],
        "status": "validationDocument.status.conf",
        "statusUpdatedAt": "2026-07-31T09:12:00.000Z",
        "validatedBy": { "firstName": "Marie", "lastName": "Durand" },
        "createdAt": "2026-07-31T06:56:41.000Z",
        "updatedAt": "2026-07-31T06:56:42.000Z"
    }
]

documentId : identifiant du document, à passer à la route de téléchargement ci-dessous.
nbPages / pageIds : un fichier téléversé est stocké page par page ; pageIds liste les identifiants de chaque page. L'image d'une page se récupère sur /{locale}/document/picture/:pageId?apiKey=xxxxx — cette route-là n'a pas de préfixe /api, contrairement à toutes les autres de cette documentation. Ne pas transposer l'une sur l'autre.
status : validationDocument.status.conf (conforme), validationDocument.status.nonConf (non conforme), validationDocument.status.incomp (incomplet), ou null si le document n'a pas encore été validé. Seules les validations faites par une agence de votre groupe sont renvoyées.
validatedBy : l'agent ayant posé ce statut, null tant que le document n'est pas validé.

Téléchargement du document en PDF — les pages sont réassemblées en un seul fichier :

/api/document/:documentId/pdf?apiKey=xxxxx

soit, en URL complète : https://flatbay.fr/fr/api/document/:documentId/pdf?apiKey=xxxxx.
Le segment /api est obligatoire ; sans lui la route n'existe pas et répond 404.

Codes d'erreur : 403 NOAPIKEY (clé absente), 403 USERNOTINGROUP (utilisateur hors de votre groupe), 404 (document introuvable ou supprimé), 413 DOCUMENTTOOLARGE (document au-delà de 30 Mo : récupérer les pages une à une via /document/picture/:pageId).

Annexe) Dictionnaire de données flatbay

Nous stockons :

Des annonces (table property)
Des utilisateurs (table user)

Ces utilisateurs peuvent être :

Des prospects : Utilisateurs venant des portails immobiliers (seloger, Leboncoin, Bien' Ici...) suite à une demande de contact depuis les portails (table mailbot)
ou des utilisateurs venant du site en marque blanche
ou des utilisateurs ayant envoyé un message depuis une annonce sur le site en marque blanche
Des candidats locataires : Utilisateurs qui ont postulé à une ou plusieurs annonce(s) (table candidate et candidate_user)
Des candidats acquéreurs : Utilisateurs qui ont fait une offre à une ou plusieurs annonce(s) (table candidate et candidate_user)
Des visiteurs : Des utilisateurs qui ont été invité ou se sont inscrits à une ou plusieurs visite(s) (table visite et visite_user)

DICTIONNAIRE