Leads via l'API

Cette section donne un accès programmatique à vos propres leads du CRM : un site web ou un formulaire externe peut envoyer des demandes directement dans l'espace personnel, et votre système peut les lire et les faire passer d'un statut à l'autre.

URL de base : https://developers.grem.capital/api/v1.

Liste

GET /leads?status=new&type=buy&priority=hot&page=1&limit=20
Authorization: Bearer gsk_live_...

Filtres : status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Les leads archivés n'apparaissent pas dans la liste normale - ajoutez archived=true. pool=true (clés d'agence uniquement) - les leads du pool commun de l'agence ; une clé personnelle l'ignore.

Les valeurs de limit (1-50, 20 par défaut) et de page (à partir de 1) hors plage sont ramenées dans la plage, et non refusées. Les autres valeurs invalides d'un paramètre connu (une valeur d'enum inconnue, une page non entière, une date invalide dans from ou to) sont refusées avec 400 validation en indiquant le champ.

Un lead

GET /leads/{id}?expand=history,documents

expand ajoute l'historique des statuts et des actions (history) et les documents joints (documents).

Structure d'un lead

• id, status, type, priority, source, tags, isArchived ; type - buy, rent, viewing, sell, contract, transfer ou user
• createdAt, updatedAt, lastActivityAt
• customer - nom, pays, messagerie et un bloc contact (phone, email, messengerHandle, profileUrl)
• budget - { value, currency }
• intent - ville, quartiers, type de transaction et intention du client
• comments - le commentaire du client et le vôtre, séparément
• object - l'annonce concernée par la demande
• agency - uniquement pour les leads d'agence : l'identifiant de l'agence et si le lead se trouve dans le pool commun

Les contacts des autres courtiers, les scores internes et les indicateurs de service ne sont jamais renvoyés.

Envoyer une demande

curl -X POST https://developers.grem.capital/api/v1/leads \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-2026-09-07-0001" \
  -d '{
    "customer": {
      "name": "Olena Kovalchuk",
      "country": "UA",
      "contact": { "phone": "+380971234567", "email": "olena@example.com" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "Looking for a 2-room flat near the metro",
    "priority": "warm",
    "consent": true
  }'

Obligatoires : customer.name et au moins un moyen de joindre le client dans customer.contact. type - buy (par défaut) ou rent. priority - hot, warm ou cold. Ajoutez objectId si la demande concerne une annonce précise, et jusqu'à dix tags de votre choix.

pool: true envoie la demande dans le pool de distribution commun au lieu de votre CRM. Par défaut, le lead vous est attribué.

Chaque lead créé via l'API est marqué avec la source «API» dans l'espace personnel, pour que vous puissiez le distinguer.

Modifier un lead

PATCH /leads/{id}
{ "status": "in progress", "priority": "hot", "tags": ["mortgage"], "brokerComments": "..." }

Vous pouvez modifier le statut, la priorité, les tags et votre propre commentaire. Un seul champ suffit. Statuts : new, in progress, processing, agreement, closed, not target, failed. Les règles de l'espace personnel s'appliquent : un lead lié à une annonce se clôture par la finalisation dans l'espace personnel (code: finalize), un lead en attente de commission conserve son statut (fee_pending), une transaction clôturée sous contrat ne se modifie que dans l'espace personnel (closed) - 422 avec la raison dans code. Autres raisons : sender (vous avez transmis le lead - c'est son destinataire qui le traite), module (un lead Swipe Match, son statut suit le module), agreement, network_readonly, forbidden.

Supprimer un lead

DELETE /leads/{id}

Cette requête archive le lead au lieu de le supprimer : il quitte la liste normale mais reste disponible avec ?archived=true. Un lead avec un contrat actif ou un accord de finalisation, un lead clôturé lié à une annonce non finalisée et un lead en attente de commission ne sont pas archivés : 422 avec code contract_active, agreement, finalize ou fee_pending.

Annonces pour un lead

GET /leads/{id}/matches?page=1&limit=20

Renvoie les annonces qui correspondent à la demande du client : le type, la ville et le budget proviennent du lead lui-même ou de l'annonce associée. Gratuit.

Pool de l'agence

Les clés d'agence disposent de deux actions sur le pool :

POST /leads/{id}/claim               take a lead from the pool
POST /leads/{id}/claim?assignTo=...  assign it to a team member
POST /leads/{id}/return-to-pool      return a lead to the pool

• Prise en charge : par défaut, le lead est attribué au propriétaire de l'agence ; assignTo (identifiant du membre) peut être transmis par le propriétaire ou un manager.
• Retour au pool : un manager ou plus, ou l'agent auquel le lead est attribué. Corps facultatif : {"reason": "..."}. Un lead archivé par les règles du pool - 422 avec code: pool_archived : restaurez-le d'abord dans l'espace personnel.
• Une clé personnelle ou un rôle insuffisant - 403 avec title: forbidden ; prendre un lead qui n'est plus dans le pool - 404.
• Les deux actions envoient un événement lead.updated.

Suivre les changements

Au lieu d'interroger la liste, abonnez-vous à lead.created et lead.updated - voir Webhooks. L'événement ne contient aucune donnée personnelle : il indique seulement quel lead a changé ; vous lisez la fiche avec une requête séparée.

Voir aussi

• Annonces - le catalogue auquel les leads font référence.
• Swipe Match - leads du module pour les courtiers partenaires.
• Webhooks - événements sur les leads nouveaux et modifiés.
• Erreurs - comprendre les refus.