Immofacile API V2 (1.1.0)

Target Audience

This documentation and APIs are designed for three distinct types of users:

• IT Departments (CIO) of large networks / Franchises: Who want to interconnect Immofacile with their proprietary internal tools.
• Developers / Partners: Commissioned by our clients to build custom showcase websites or specific business applications.
• Software Vendors (PropTech / Ecosystem Partners): Valuation tools, marketing automation providers, and any type of partner we want to connect to our system.
• Real estate listing portals: Currently fed mostly via CSV or XML feeds, APIs are needed to better manage listing distribution and lead returns.

1. API Platform Overview

The Immofacile API is built on REST standards. It uses standard HTTP request methods, explicit HTTP status codes, and a JSON response format.

1.1 "API-First" Philosophy

To support the digitalization of real estate agencies, Immofacile offers a bidirectional architecture:

• Extraction (Read): Securely access your client data (properties, contacts, events, etc.).
• Injection (Write): Create, update, or enrich the agency database (leads, properties, actions, etc.) while respecting the CRM's business rules.

1.2 Environments & Authentication

• Sandbox (Test): An isolated environment containing demo data for development without risk of polluting production (coming soon).
• Production: The agency's live environment.
• 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.

2. Key Concepts & Operating Rules

To 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.

2.1 Discovery (Entry Point Discovery)

To avoid hardcoding URLs and to dynamically adapt to the client agency's access rights, our API implements the Discovery principle.

• 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.).
• Example request: GET https://api.immofacile.com/v2/

2.2 Webhooks (Real-Time Events)

Intensive 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.

• Event format: Each payload sent by our Webhook contains the event type (event_type) and the identifier of the related resource.

3. Business Use Cases & Implementation

Here is how to orchestrate our APIs to meet the real-world needs of real estate agents.

Use Case 1: Create / Update a Lead from an External Tool (Data Write)

• 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.
  • Action: POST /customers/search with email criterion
• Step 2: Contact creation — If the contact does not exist, create it.
  • Action: POST /customers
  • Payload: {"firstname": "Jean", "lastname": "Dupont", "phone": "0601020304", "type": "Prospect Vendeur"}
• Step 3: Search project creation — Create the search project based on the property the contact inquired about.
• Step 4: Add property to contact follow-up — Associate the listing details to the contact so the agent has context during callback.

Use Case 2: Real-Time Feed for Agency Website / Portal / Partner (Data Read & Webhooks)

• Step 1: Initialization (Full Sync) — On first connection, retrieve the entire active catalog.
• Step 2: Listen for updates (Delta Sync via Webhook) — Register the website URL on our webhook to listen for the property.updated event.
  • Action: Configuration via dashboard or POST /hooks to subscribe to property.updated.
• 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.

4. Support & Escalation

Having trouble with your integration?

1. Check the Logs: Every error response from our API contains a unique request_id.
2. 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).

Packs

The API is organized into packs:

• Products — Property listings management
• Customers — Customer management, search requests, follow-ups, actions
• Leads — Seller and buyer lead creation
• Users — Agent/collaborator management
• Agencies — Agency information
• Discovery — Scope discovery
• Webhooks — Event subscriptions

Access packs (endpoint badges)

Each endpoint carries one or more colored badges indicating which subscription pack(s) grant access to it. An endpoint may belong to several packs. Use these badges to check whether your subscription covers a given endpoint.

Authentication

Obtain a Bearer token via POST /api/client/token/site (OAuth2 client credentials). Include it in the Authorization: Bearer {token} header for all requests.

Base URL is dynamic. The token response includes a domain field. Use it as the base for every subsequent call ({domain}/api/v2/site/...). In the Try it console, set the domain server variable to that value.

Error format

Pagination

List endpoints use cursor-based pagination: next_cursor + has_more.

Headers

All responses include X-Request-Id (UUID) for log correlation.