Skip to content

Create a product
Properties
Full

Request

Creates a new product (property listing).

Criteria (criteria field):

  • Each criterion is an object with id (criteria identifier) and value.

  • The id accepts either the XML identifier (e.g. "TypeBien", "NbPieces", "Surface") or the numeric ID (e.g. "27"). Both are resolved by the API.

  • Value format depends on criteria type: string for UNIQUE, number for NUMBER, boolean 0/1 for FLAG, array for MULTIPLE, ISO date for DATE.

  • For UNIQUE/MULTIPLE types, the value must exactly match a valid value code (model field) from the referential. Use GET /criterias/product/{id} to discover valid values.

    For example:

    • ✅ Correct: {"id": "TypeBien", "value": "1"}
    • ❌ Wrong: {"id": "TypeBien", "value": "Appartement"} (this is the value label, not the value code)

    The criteria endpoint (GET /criterias/product/{id}) returns value objects like:

    { "id": "6", "model": "1", "label": "Appartement" }

    You must use the model field as the value in your criteria array.

Product status (Statut criterion):

  • The product is only active and visible in the interface when Statut = "EnCours".
  • If you do NOT send the Statut criterion, the system applies the site's default value (configured per site). This default is usually "EnCours" (active), but some sites may have a different default — in that case the product may not be immediately visible in the interface.
  • Recommendation: Always explicitly include {"id": "Statut", "value": "EnCours"} in your criteria array to ensure the product is immediately active.

DPE (Energy Performance):

  • Send numeric values via conso_energ (kWh/m²/year) and valeur_GES (kgCO₂/m²/year).
  • The system automatically calculates the DPE/GES letter (A-G) from numerical values based on property type and country.
  • If you already know the letter, send it directly via ConsoEner / GES criteria instead.

Geolocation (GPS):

  • If the Alentour criterion is provided (format "lat,lng", e.g. "48.8566,2.3522"), it is used directly as the property's GPS coordinates.
  • If Alentour is NOT provided, the system automatically geocodes from Adresse + CodePostal + Ville criteria. Fallback: geocodes from city+postal code only.

Model (reference):

  • The model field is the property's internal reference number (mandate number, agency reference).
  • If omitted, the system auto-generates the next available reference for the agency.
  • You can use it to store your own identifier for cross-referencing.

Rooms (rooms field):

  • Each room has a type (validated against referential list 1), optional surface, niveau, exposition (list 2), vue (list 3), sol (list 4), commentaire.
  • Use GET /configs/listes/{listeId}/values to discover valid values (1=room types, 2=expositions, 3=views, 4=floor types).
Security
bearerAuth
Bodyapplication/jsonrequired
agency_idintegerrequired

Agency ID for the product. Must be within the authenticated site's scope (validated by manufacturer_in_scope). Use GET /agencies to list available IDs.

Example:123
user_idinteger or null

Assigned user (agent) ID. The agent responsible for this property listing.

Example:456
modelstring or null

Product reference (mandate number, agency reference, your own identifier). Auto-generated if omitted — the system produces the next sequential reference for the agency. You can use this field to store your own cross-reference ID.

Example:"REF-2025-001"
descriptionsArray of objects or null

Web descriptions for the product (multilingual). Each entry requires a language_code (ISO 639-2, e.g. "fr").

criteriaArray of objectsrequired

Product criteria array. Required.

Each criterion is an object with:

  • id — Either the XML key (e.g. "TypeBien") or numeric ID (e.g. "27"). Both are resolved by the API.
  • value — Format depends on criteria type:
    • UNIQUE: exact value code string from the referential (the model field from GET /criterias/product/{id}, e.g. "1" (label "Appartement"), NOT the numeric ID like "6")
    • NUMBER: numeric value as string (e.g. "85.5")
    • FLAG: 0 or 1
    • TEXT: free text string
    • MULTIPLE: array of value code strings
    • DATE: ISO 8601 datetime or dd/MM/yyyy

Mandatory criteria:

  • TypeBien (ID 27) — Property type (e.g. "1" (Appartement), "2" (Maison))
  • TypeTransaction (ID 28) — Transaction type (e.g. "Vente", "Location")
  • CPVille (ID 65) — Or alternatively CodePostal + Ville (auto-composed)

Recommended criteria:

  • Statut — Product status. Must be "EnCours" for the product to be active and visible. If omitted, the site's default applies (which may create an inactive product).

DPE auto-calculation: If you provide conso_energ (numeric) without ConsoEner (letter), the system auto-calculates the DPE letter based on property type and country. Same for valeur_GES → GES.

GPS auto-geocoding: If you provide Adresse + CodePostal + Ville without Alentour, the system geocodes the address automatically. Provide Alentour directly (format "lat,lng") to bypass geocoding.

Use GET /criterias/product/all to discover available criteria and GET /criterias/product/{id} for valid values.

Example:
[ { "id": "TypeBien", "value": "1" }, { "id": "TypeTransaction", "value": "Vente" }, { "id": "Statut", "value": "EnCours" }, { "id": "NbPieces", "value": "4" }, { "id": "Surface", "value": "85.5" }, { "id": "Prix", "value": "350000" }, { "id": "conso_energ", "value": "125" }, { "id": "Adresse", "value": "12 rue de la Paix" }, { "id": "CodePostal", "value": "75002" }, { "id": "Ville", "value": "Paris" } ]
roomsArray of objects or null

Room list. Each room requires a type from referential list 1. Use GET /configs/listes/1/values to discover room types.

FieldRequiredValidationDescription
typeYeslist 1Room type (e.g. "Chambre", "Cuisine")
niveauNonumericFloor level
surfaceNonumericSurface in m²
expositionNolist 2Exposure (Nord, Sud, Est, Ouest...)
vueNolist 3View (Jardin, Mer, Rue...)
solNolist 4Floor type (Parquet, Carrelage...)
commentaireNostringFree comment
customer_idinteger or null

Existing customer ID to link as the property owner/seller. Mutually exclusive with customer object.

Example:789
customerobject

Create a new customer and link as owner. Used when customer_id is not provided.

curl -i -X POST \
  https://api-doc.immo-facile.com/_mock/openapi/products \
  -H 'Authorization: Bearer <YOUR_opaque_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "agency_id": 123,
    "user_id": 456,
    "model": "REF-2025-001",
    "descriptions": [
      {
        "title": "Bel appartement lumineux",
        "description": "Situé au 3ème étage avec ascenseur, cet appartement...",
        "language_code": "fr"
      }
    ],
    "criteria": [
      {
        "id": "TypeBien",
        "value": "1"
      },
      {
        "id": "TypeTransaction",
        "value": "Vente"
      },
      {
        "id": "Statut",
        "value": "EnCours"
      },
      {
        "id": "NbPieces",
        "value": "4"
      },
      {
        "id": "Surface",
        "value": "85.5"
      },
      {
        "id": "Prix",
        "value": "350000"
      },
      {
        "id": "conso_energ",
        "value": "125"
      },
      {
        "id": "Adresse",
        "value": "12 rue de la Paix"
      },
      {
        "id": "CodePostal",
        "value": "75002"
      },
      {
        "id": "Ville",
        "value": "Paris"
      }
    ],
    "rooms": [
      {
        "type": "Chambre",
        "niveau": 0,
        "surface": 14.5,
        "exposition": "string",
        "vue": "string",
        "sol": "string",
        "commentaire": "string"
      }
    ],
    "customer_id": 789,
    "customer": {}
  }'

Responses

Product created

Bodyapplication/json
dataobject
Response
{ "data": { "id": 0 } }