Skip to content

Create a buyer lead
Leads
Websites

Request

Creates a buyer lead with a customer and optional search requests. Requires SITE_LEADS permission and RS:LEADS_BUYER right.

Synchronization & duplicate behavior: Same as seller leads (see above).

Search requests: Each search request contains criteria with operators:

  • EGAL — Equals (exact match)
  • SUPERIEUR — Greater than or equal
  • INFERIEUR — Less than or equal
  • CONTIENT — Contains (for text/multi-value, e.g. zones)
  • DIFFERENT — Not equal

Use GET /criterias/search-requests to discover available search criteria for your site.

Customer address: Include address fields directly in the customer object (address, postalcode, city, country, latitude, longitude).

User assignment: Same auto-assignment logic as seller leads when user_id is omitted.

Security
bearerAuth
Bodyapplication/jsonrequired
agency_idintegerrequired

Target agency ID. Must be within the authenticated site's scope.

Example:123
user_idinteger or null

Assigned user (agent) ID. When omitted, auto-assigned via the configured lead distribution rule.

Example:456
check_duplicateboolean or null

Same duplicate behavior as seller leads:

  • false/omitted: silently updates existing duplicate
  • true: returns 409 on duplicate
customerobject(LeadCustomer)required

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

search_requestArray of objects or null(LeadSearchRequest)

One or more search requests to create for the buyer. Each defines the buyer's search criteria (what they are looking for).

product_idinteger or null

Existing product ID to follow. When provided, the buyer is linked to this product via a follow-up action. Optional.

Example:12345
commentstring or null

Free-text comment attached to the follow-up action (only used when product_id is provided).

Example:"Client très intéressé, rappeler rapidement"
curl -i -X POST \
  https://api-doc.immo-facile.com/_mock/openapi/leads/buyers \
  -H 'Authorization: Bearer <YOUR_opaque_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "agency_id": 123,
    "user_id": 456,
    "check_duplicate": false,
    "customer": {
      "firstname": "Pierre",
      "lastname": "Durand",
      "email": "pierre.durand@example.com",
      "mobile_phone": "+33611223344",
      "gender": "M",
      "group": 1,
      "address": "5 place Bellecour",
      "postalcode": "69002",
      "city": "Lyon"
    },
    "search_request": [
      {
        "wording": "Appartement T3 Lyon",
        "activated": true,
        "alert_email": true,
        "criteria": [
          {
            "id": "TypeBien",
            "operator": "EGAL",
            "value": "Appartement"
          },
          {
            "id": "NbPieces",
            "operator": "SUPERIEUR",
            "value": "2"
          },
          {
            "id": "Prix",
            "operator": "INFERIEUR",
            "value": "300000"
          },
          {
            "id": "Surface",
            "operator": "SUPERIEUR",
            "value": "55"
          }
        ]
      }
    ],
    "comment": "Recherche active, budget flexible"
  }'

Responses

Lead created successfully

Bodyapplication/json
dataobject
Response
{
  "data": {
    "customer_id": 790,
    "search_request_id": [ … ]
  }
}