Creates a new product (property listing).
Criteria (criteria field):
Each criterion is an object with
id(criteria identifier) andvalue.The
idaccepts 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 (
modelfield) from the referential. UseGET /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
modelfield as thevaluein your criteria array.- ✅ Correct:
Product status (Statut criterion):
- The product is only active and visible in the interface when
Statut = "EnCours". - If you do NOT send the
Statutcriterion, 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) andvaleur_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/GEScriteria instead.
Geolocation (GPS):
- If the
Alentourcriterion is provided (format"lat,lng", e.g."48.8566,2.3522"), it is used directly as the property's GPS coordinates. - If
Alentouris NOT provided, the system automatically geocodes fromAdresse+CodePostal+Villecriteria. Fallback: geocodes from city+postal code only.
Model (reference):
- The
modelfield 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), optionalsurface,niveau,exposition(list 2),vue(list 3),sol(list 4),commentaire. - Use
GET /configs/listes/{listeId}/valuesto discover valid values (1=room types, 2=expositions, 3=views, 4=floor types).
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.
Assigned user (agent) ID. The agent responsible for this property listing.
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.
Web descriptions for the product (multilingual). Each entry requires a language_code (ISO 639-2, e.g. "fr").
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
modelfield fromGET /criterias/product/{id}, e.g."1"(label "Appartement"), NOT the numeric ID like"6") - NUMBER: numeric value as string (e.g.
"85.5") - FLAG:
0or1 - TEXT: free text string
- MULTIPLE: array of value code strings
- DATE: ISO 8601 datetime or
dd/MM/yyyy
- UNIQUE: exact value code string from the referential (the
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 alternativelyCodePostal+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.
[ { "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" } ]
Room list. Each room requires a type from referential list 1. Use GET /configs/listes/1/values to discover room types.
| Field | Required | Validation | Description |
|---|---|---|---|
type | Yes | list 1 | Room type (e.g. "Chambre", "Cuisine") |
niveau | No | numeric | Floor level |
surface | No | numeric | Surface in m² |
exposition | No | list 2 | Exposure (Nord, Sud, Est, Ouest...) |
vue | No | list 3 | View (Jardin, Mer, Rue...) |
sol | No | list 4 | Floor type (Parquet, Carrelage...) |
commentaire | No | string | Free comment |
Existing customer ID to link as the property owner/seller. Mutually exclusive with customer object.
- Mock serverhttps://api-doc.immo-facile.com/_mock/openapi/products
- https://v2.immo-facile.com/api/v2/sitehttps://v2.immo-facile.com/api/v2/site/products
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": {}
}'