Client API Documentation

Introduction

Welcome to the CRM Client API. This API provides a single webhook endpoint designed for clients to programmatically fetch data securely. We utilize a highly optimized backend to deliver enriched datasets in real-time.

POST https://api.marketing-lab.immo/api/v1

Authentication

All API requests are authenticated using an API Key. This key is securely mapped to your authorized database, regions, and pull statuses.

You can authenticate by passing your key in the request headers (recommended) or in the JSON body.

x-api-key: YOUR_API_KEY

Retrieves a list of all geographical regions your API key is authorized to access.

{
  "operation": "getRegions"
}

[
  {
    "id": 30,
    "nom": "Occitanie"
  },
  {
    "id": 62,
    "nom": "Provence-Alpes-Côte d'Azur"
  }
]

Fetches a list of real estate programmes belonging to your authorized regions.

{
  "operation": "getProgrammes"
}

[
  {
    "id": 145,
    "idRegion": 30,
    "nom": "Les Jardins de l'Aube"
  }
]

Retrieves a list of up to 200 contacts that are currently marked as "Ready to Pull". This operation is completely read-only and will not change the status of the contacts.

{
  "operation": "readContacts"
}

[
  {
    "action_id": 1045,
    "prospect_id": 5002,
    "programme_id": 145,
    "prospect_nom": "Dupont",
    "prospect_prenom": "Jean",
    "prospect_telephone": "+33612345678",
    "prospect_email": "jean@email.com",
    "programme_nom": "Les Jardins de l'Aube",
    "region_nom": "Occitanie",
    "origine_designation": "Website form",
    "type_contact_designation": "Inbound Lead",
    "type_action_designation": "Contact request"
    // ... additional enriched fields
  }
]

Retrieves a list of contacts and immediately updates their status in the CRM to mark them as "Pulled". It also timestamps the exact moment of the pull.

{
  "operation": "pullContacts"
}

Retrieves a list of up to 500 contacts that have already been pulled within the last 30 days.

{
  "operation": "getPulledContacts"
}

Error Handling

If an invalid API Key is provided, or an unknown operation is requested, the API will return a 401 Unauthorized or 400 Bad Request status.

{
  "valid": false,
  "error": "Invalid API Key"
}