{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-openapi.yaml","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"openapi.yaml","settings":{"baseUrlPath":"/openapi"},"disableAutoScroll":true,"seo":{"title":"Immofacile API V2","llmstxt":{"hide":true}},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"Immofacile API V2","version":"1.1.0","description":"# Welcome to the Immofacile API\n\nThis documentation will guide you through integrating with Immofacile, the leading SaaS CRM for real estate agencies. Our REST APIs allow you to connect your applications, automate your business workflows, and extend the power of our ecosystem.\n\n## Target Audience\n\nThis documentation and APIs are designed for three distinct types of users:\n\n- **IT Departments (CIO) of large networks / Franchises:** Who want to interconnect Immofacile with their proprietary internal tools.\n- **Developers / Partners:** Commissioned by our clients to build custom showcase websites or specific business applications.\n- **Software Vendors (PropTech / Ecosystem Partners):** Valuation tools, marketing automation providers, and any type of partner we want to connect to our system.\n- **Real estate listing portals:** Currently fed mostly via CSV or XML feeds, APIs are needed to better manage listing distribution and lead returns.\n\n## 1. API Platform Overview\n\nThe Immofacile API is built on **REST** standards. It uses standard HTTP request methods, explicit HTTP status codes, and a JSON response format.\n\n### 1.1 \"API-First\" Philosophy\n\nTo support the digitalization of real estate agencies, Immofacile offers a bidirectional architecture:\n\n- **Extraction (Read):** Securely access your client data (properties, contacts, events, etc.).\n- **Injection (Write):** Create, update, or enrich the agency database (leads, properties, actions, etc.) while respecting the CRM's business rules.\n\n### 1.2 Environments & Authentication\n\n- **Sandbox (Test):** An isolated environment containing demo data for development without risk of polluting production (coming soon).\n- **Production:** The agency's live environment.\n- **Security:** Authentication relies on the **OAuth 2.0** protocol (via a `Client ID` and `Client Secret` generated from the Immofacile admin dashboard) or by **API Key** for simple internal script integrations.\n\n## 2. Key Concepts & Operating Rules\n\nTo interact effectively with Immofacile, you must understand two core pillars of our architecture: the **Discovery API** for accessing authorized resources, and **Webhooks** for real-time synchronization.\n\n### 2.1 Discovery (Entry Point Discovery)\n\nTo avoid hardcoding URLs and to dynamically adapt to the client agency's access rights, our API implements the **Discovery** principle.\n\n- **The concept:** By querying the single entry point, the API returns the list of all resources you have access to, along with associated URLs and available actions (`GET`, `POST`, etc.).\n- **Example request:** `GET https://api.immofacile.com/v2/`\n\n### 2.2 Webhooks (Real-Time Events)\n\nIntensive polling is prohibited on our platform. To synchronize your data in real time, you must use our **Webhooks** system. Rather than asking Immofacile whether data has changed, Immofacile sends an HTTP `POST` notification to your server as soon as an event occurs.\n\n- **Event format:** Each payload sent by our Webhook contains the event type (`event_type`) and the identifier of the related resource.\n\n## 3. Business Use Cases & Implementation\n\nHere is how to orchestrate our APIs to meet the real-world needs of real estate agents.\n\n### Use Case 1: Create / Update a Lead from an External Tool (Data Write)\n\n- **Step 1:** Duplicate check — Before creating a contact, the third-party application must verify the prospect does not already exist in the agency database via email or phone.\n  - Action: `POST /customers/search` with email criterion\n- **Step 2:** Contact creation — If the contact does not exist, create it.\n  - Action: `POST /customers`\n  - Payload: `{\"firstname\": \"Jean\", \"lastname\": \"Dupont\", \"phone\": \"0601020304\", \"type\": \"Prospect Vendeur\"}`\n- **Step 3:** Search project creation — Create the search project based on the property the contact inquired about.\n- **Step 4:** Add property to contact follow-up — Associate the listing details to the contact so the agent has context during callback.\n\n### Use Case 2: Real-Time Feed for Agency Website / Portal / Partner (Data Read & Webhooks)\n\n- **Step 1:** Initialization (Full Sync) — On first connection, retrieve the entire active catalog.\n- **Step 2:** Listen for updates (Delta Sync via Webhook) — Register the website URL on our webhook to listen for the `property.updated` event.\n  - Action: Configuration via dashboard or `POST /hooks` to subscribe to `property.updated`.\n- **Step 3:** Targeted update — When a price changes or a property is sold in Immofacile, the website receives the webhook. It then queries the specific property to update its local database.\n\n## 4. Support & Escalation\n\n**Having trouble with your integration?**\n\n1. **Check the Logs:** Every error response from our API contains a unique `request_id`.\n2. **Contact dev support:** Send an email to api.imf@orisha.com, always including the `request_id`, the sent payload, and the environment concerned (Sandbox or Prod).\n\n---\n\n## Packs\n\nThe API is organized into packs:\n- **Products** — Property listings management\n- **Customers** — Customer management, search requests, follow-ups, actions\n- **Leads** — Seller and buyer lead creation\n- **Users** — Agent/collaborator management\n- **Agencies** — Agency information\n- **Discovery** — Scope discovery\n- **Webhooks** — Event subscriptions\n\n### Access packs (endpoint badges)\n\nEach endpoint carries one or more colored badges indicating which\nsubscription pack(s) grant access to it. An endpoint may belong to\nseveral packs. Use these badges to check whether your subscription\ncovers a given endpoint.\n\n| Badge | Access pack | Color |\n|-------|-------------|-------|\n| 🟣 **Customers** | Customers, search requests, follow-ups, actions | purple |\n| 🟢 **Properties** | Property listings and criteria | green |\n| 🟠 **Leads** | Seller and buyer lead creation | orange |\n| 🔴 **Sales** | Sale agreements, offers, leases | red |\n| 🟪 **Websites** | Read feeds for websites and portals | blueberry |\n\n## Authentication\n\nObtain a Bearer token via `POST /api/client/token/site` (OAuth2 client credentials).\nInclude it in the `Authorization: Bearer {token}` header for all requests.\n\n**Base URL is dynamic.** The token response includes a `domain` field. Use it\nas the base for every subsequent call (`{domain}/api/v2/site/...`). In the\nTry it console, set the `domain` server variable to that value.\n\n## Error format\n```json\n{ \"error\": { \"code\": \"ERROR_CODE\", \"message\": \"Human-readable message.\" } }\n```\n\n## Pagination\nList endpoints use cursor-based pagination: `next_cursor` + `has_more`.\n\n## Headers\nAll responses include `X-Request-Id` (UUID) for log correlation.\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"api-doc.immo-facile.com","port":4000,"ipAddress":"216.73.216.114"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/openapi","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}