Documentation de l'API

Intégrez-vous de manière transparente à la plateforme Marketing Lab pour synchroniser les régions, les programmes immobiliers et filtrer la récupération automatique des derniers contacts générés.

v1.3 Vérification du statut...

Introduction

Bienvenue sur l'API Marketing Lab. Cette API fournit un point d'accès unifié compatible avec les méthodes GET (query parameters inline) et POST (payload JSON). Elle vous permet d'extraire, filtrer et gérer vos prospects et programmes immobiliers en temps réel.

URL de base du Proxy

HTTP Endpoint 
GET / POST https://api.marketing-lab.immo/api/v1

Authentification

Toutes les requêtes à l'API requièrent une clé API valide. Vous pouvez transmettre votre clé de trois manières différentes :

Recommandé

En-tête HTTP (Header)

x-api-key: VOTRE_CLE_API
URL Inline (GET)

Query Parameter

?apiKey=VOTRE_CLE_API
JSON Body (POST)

Payload Body

{ "apiKey": "VOTRE_CLE_API" }
Sécurité & Portée : Chaque clé API est rattachée à une base de données spécifique et à une liste stricte de régions autorisées (ex: clé YOUR_API_KEY limitée à la région ID 34).

Filtres & Options de Sélection

Vous pouvez affiner et filtrer les données renvoyées par l'API en ajoutant des paramètres de filtrage dans l'URL (requêtes GET) ou dans le corps JSON (requêtes POST).

Paramètre Type Opérations supportées Description & Exemple
idRegion / regionId Integer / Array Toutes Filtre les données pour une ou plusieurs régions (ex: 34). Attention: La région doit faire partie des régions autorisées par votre clé API.
programme_id / programmeId Integer / String getProgrammes, readContacts, pullContacts, getPulledContacts Filtre les résultats par ID(s) de programme(s) spécifique(s) (ex: 863 ou 863,145).
startDate / from String / ISO readContacts, pullContacts, getPulledContacts Filtre les contacts dont la date d'action est supérieure ou égale à cette date (ex: 2026-01-01 ou 20260101000000).
endDate / to String / ISO readContacts, pullContacts, getPulledContacts Filtre les contacts dont la date d'action est inférieure ou égale à cette date (ex: 2026-07-31).
isActif / status Integer (0 ou 1) getProgrammes Filtre les programmes par statut actif (1) ou inactif (0).
limit Integer Toutes requêtes de sélection Nombre maximal d'enregistrements à retourner (par défaut: 200 pour contacts, 500 pour pulled, max: 1000).
offset Integer Toutes requêtes de sélection Décalage de pagination pour les enregistrements (par défaut: 0).

Exemple GET avec Filtres Inline

GET /api/v1?apiKey=YOUR_API_KEY&operation=readContacts&idRegion=34&programme_id=863&limit=50 HTTP/1.1
Host: api.marketing-lab.immo

Exemple POST avec Filtres JSON

{
  "apiKey": "YOUR_API_KEY",
  "operation": "readContacts",
  "idRegion": 34,
  "programme_id": 863,
  "startDate": "2026-01-01",
  "limit": 50
}

Dictionnaire des Valeurs Connues (Known Values)

Retrouvez ci-dessous la liste exhaustive des valeurs possibles et des énumérations pour les différents champs de la base de données renvoyés par l'API.

👤

Civilité (civility / GENRE)

Valeurs possibles pour le titre de civilité du prospect :

Monsieur Madame Mademoiselle M. et Mme
🏠

Destination d'Achat (destination_designation)

Type de projet d'achat immobilier recherché :

Résidence Principale Résidence Secondaire Investissement / Pinel / LMNP Locatif
🏢

Type de Logement (type_logt_designation)

Nature du bien recherché par le client :

Appartement Maison Studio Terrain Parking / Box
📐

Taille du Logement (taille_logt_designation)

Typologie et nombre de pièces recherchés :

T1 / 1 pièce T2 / 2 pièces T3 / 3 pièces T4 / 4 pièces T5 / 5 pièces et +
🌐

Type de Contact (type_contact_designation)

Canal et méthode de saisie initiale de la demande :

Inbound Lead Formulaire Web Téléphone / Call Center Partenaire / Portail Passage Bureau de Vente

Récupérer les régions

GET / POST

Récupère la liste des régions autorisées pour la clé API fournie. Accepte le filtre optionnel idRegion.

Requête Exemple

GET https://api.marketing-lab.immo/api/v1?apiKey=YOUR_API_KEY&operation=getRegions

Réponse 200 OK

[
  {
    "id": 34,
    "nom": "Region A"
  }
]

Récupérer les programmes

GET / POST

Récupère la liste des programmes immobiliers. Supporte le filtrage par idRegion, programme_id, isActif, limit et offset.

Requête Exemple avec Filtres

GET https://api.marketing-lab.immo/api/v1?apiKey=YOUR_API_KEY&operation=getProgrammes&idRegion=34&limit=2

Réponse 200 OK

[
  {
    "id": 863,
    "nom": "Programme A",
    "code": "PROG_A",
    "idRegion": 34,
    "ville": "PARIS",
    "isActif": 1,
    "dateMAJ": "2026-07-16 09:25:04"
  }
]

Lire les contacts

GET / POST

Récupère les contacts actuellement prêts à être récupérés (lecture seule sans modification de statut). Supporte les filtres idRegion, programme_id, startDate, endDate, limit.

Requête Exemple

{
  "apiKey": "YOUR_API_KEY",
  "operation": "readContacts",
  "idRegion": 34,
  "limit": 20
}

Réponse 200 OK

[
  {
    "action_id": 1045,
    "prospect_id": 5002,
    "programme_id": 863,
    "prospect_nom": "Doe",
    "prospect_prenom": "John",
    "prospect_telephone": "+33612345678",
    "prospect_email": "john.doe@example.com",
    "programme_nom": "Programme A",
    "region_nom": "Region A",
    "origine_designation": "Google",
    "type_contact_designation": "Inbound Lead",
    "destination_designation": "Résidence Principale"
  }
]

Récupérer (Pull) les contacts

POST

Récupère les contacts et met à jour leur statut immédiatement en base pour les marquer comme récupérés (passage du statut 5 à 3 pour Promogim).

Mutation des données : Une fois récupérés via pullContacts, les contacts ne réapparaîtront plus dans les requêtes readContacts ultérieures.

Obtenir les contacts déjà récupérés

GET / POST

Récupère l'historique des contacts qui ont déjà été récupérés (statut post-pull) au cours de la période demandée ou des 30 derniers jours par défaut.

Requête Exemple

{
  "apiKey": "YOUR_API_KEY",
  "operation": "getPulledContacts",
  "limit": 50
}

Réponse 200 OK

[
  {
    "action_id": 1045,
    "prospect_id": 5002,
    "date_action_future": "2026-07-23 11:32:00",
    "prospect_nom": "Doe",
    "prospect_prenom": "John",
    "programme_nom": "Programme A",
    "region_nom": "Region A"
  }
]

Créer un programme

POST

Créez un nouveau programme immobilier dans votre région autorisée. Écrit un log de traçabilité dans la base log.

Corps de la requête (POST)

{
  "apiKey": "YOUR_API_KEY",
  "operation": "createProgramme",
  "data": {
    "nom": "Nouveau Programme FSB",
    "idRegion": 34,
    "ville": "Paris",
    "isActif": 1
  }
}

Réponse 200 OK

[
  {
    "affectedRows": 1,
    "insertId": 864
  }
]

Mettre à jour un programme

POST

Mettez à jour un programme immobilier existant dans votre région autorisée. Écrit un log de traçabilité dans la base log.

Corps de la requête (POST)

{
  "apiKey": "YOUR_API_KEY",
  "operation": "updateProgramme",
  "programme_id": 863,
  "data": {
    "nom": "Programme A Modifié",
    "isActif": 1
  }
}

Réponse 200 OK

[
  {
    "affectedRows": 1,
    "changedRows": 1
  }
]

Créer une région

POST

Créez une nouvelle région géographique en base. Écrit un log de traçabilité dans la base log.

Corps de la requête (POST)

{
  "apiKey": "YOUR_API_KEY",
  "operation": "createRegion",
  "data": {
    "nom": "Nouvelle Région FSB"
  }
}

Réponse 200 OK

[
  {
    "affectedRows": 1,
    "insertId": 41
  }
]

Mettre à jour une région

POST

Mettez à jour les informations d'une région existante. Nécessite l'autorisation d'accès à cette région. Écrit un log de traçabilité dans la base log.

Corps de la requête (POST)

{
  "apiKey": "YOUR_API_KEY",
  "operation": "updateRegion",
  "region_id": 34,
  "data": {
    "nom": "Region A Est"
  }
}

Réponse 200 OK

[
  {
    "affectedRows": 1,
    "changedRows": 1
  }
]

Gestion des erreurs

En cas d'erreur de clé, d'opération invalide ou de filtre non autorisé (ex: demande d'une région hors périmètre), l'API renvoie un objet JSON décrivant l'erreur.

{
  "valid": false,
  "error": "Unauthorized regionId update. Allowed: 34"
}