Skip to content

Leads

Seller and buyer lead creation from external tools.

Operations

Create a seller lead
Leads
Websites

Request

Creates a seller lead with a customer and a product. Requires SITE_LEADS permission and RS:LEADS_SELLER right.

Synchronization & duplicate behavior:

  • The system automatically checks for duplicate customers by email OR phone OR mobile_phone.
  • Without check_duplicate (or false): if a duplicate is found, the existing contact is silently updated with the provided data and linked to the product. The returned customer_id is the existing one.
  • With check_duplicate: true: returns HTTP 409 with error code CONFLICT when a duplicate is found. You must then decide to proceed without the flag or skip.

Customer address: Include address fields directly in the customer object (address, postalcode, city, country, latitude, longitude). These are persisted on the contact record.

Product creation: If product_id is not provided, a product is created from the product object. Criteria follow the same rules as POST /products:

  • id accepts either the XML key (e.g. "TypeBien") or the numeric ID (e.g. "27")
  • value format depends on criteria type
  • DPE is auto-calculated from conso_energ / valeur_GES if letters are not provided
  • GPS is auto-geocoded from Adresse + CodePostal + Ville if Alentour is not provided

User assignment: If user_id is omitted, the system uses the configured lead distribution rule (DEFAULT_LEADS_AFFECTATION) to automatically assign a user within the target agency.

Security
bearerAuth
Bodyapplication/jsonrequired
agency_idintegerrequired

Target agency ID. Must be among the agencies accessible from the authenticated site. Use GET /agencies to discover available IDs.

Example:123
user_idinteger or null

Assigned user (agent) ID. When omitted, the system uses the configured lead distribution rule (DEFAULT_LEADS_AFFECTATION) to automatically assign a user within the target agency.

Example:456
check_duplicateboolean or null

Controls duplicate behavior:

  • false or omitted (default): if a duplicate customer is found by email OR phone OR mobile_phone, the existing contact is silently updated and linked to the product.
  • true: returns HTTP 409 with error code CONFLICT when a duplicate is found.
customerobject(LeadCustomer)required

Customer data for the lead. Uses snake_case field names. Duplicate detection is performed on email OR phone OR mobile_phone.

product_idinteger or null

Existing product ID to link the seller lead to. Mutually exclusive with the product object — provide one or the other, not both. The product must exist and be within the site scope.

Example:99999
productobject

Product to create (required if product_id is not provided). Criteria follow the same rules as POST /products:

  • id accepts either the XML key (e.g. "TypeBien") or numeric ID (e.g. "27")
  • value format depends on criteria type (see Products documentation)
  • DPE auto-calculated, GPS auto-geocoded (see Products pack for details)
curl -i -X POST \
  https://api-doc.immo-facile.com/_mock/openapi/leads/sellers \
  -H 'Authorization: Bearer <YOUR_opaque_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "agency_id": 123,
    "user_id": 456,
    "check_duplicate": true,
    "customer": {
      "firstname": "Marie",
      "lastname": "Martin",
      "email": "marie.martin@example.com",
      "phone": "+33698765432",
      "gender": "F",
      "group": 4,
      "address": "10 rue des Lilas",
      "postalcode": "69001",
      "city": "Lyon"
    },
    "product": {
      "criteria": [
        {
          "id": "TypeBien",
          "value": "Maison"
        },
        {
          "id": "TypeTransaction",
          "value": "Vente"
        },
        {
          "id": "Surface",
          "value": "120"
        },
        {
          "id": "NbPieces",
          "value": "5"
        },
        {
          "id": "CodePostal",
          "value": "69001"
        },
        {
          "id": "Ville",
          "value": "Lyon"
        }
      ]
    }
  }'

Responses

Lead created successfully

Bodyapplication/json
dataobject
Response
{
  "data": {
    "customer_id": 789,
    "product_id": 12345
  }
}