Swipe Match trouve un courtier pour un client et propose le lead aux courtiers à tour de rôle. Via l'API, un courtier partenaire (ou une agence) voit les leads qui lui sont proposés et attribués, et déclare ses étapes avec le client. La lecture nécessite le scope leads:read, les événements nécessitent leads:write. Non facturé.
Leads
curl "https://developers.grem.capital/api/v1/match/leads?view=active&limit=20" \
-H "Authorization: Bearer gsk_live_xxx"
GET /match/leads :
| Paramètre | Description |
|---|---|
view | active (par défaut) - leads qui vous sont attribués ; inbox - offres ouvertes qui vous sont faites. Une clé d'agence voit les leads et les offres des agents de l'agence |
stage | filtre par étape |
page, limit | page ; limit jusqu'à 50, 20 par défaut ; limit ou page inférieur à 1, limit supérieur à 50 ou page supérieur à 1000 - 400 |
GET /match/leads/{id} - un lead, GET /match/leads/{id}/events - son historique (vos événements et vos offres ; ni événements financiers ou techniques, ni notes du client). Le lead de quelqu'un d'autre - 404.
Tant que Swipe Match n'est pas ouvert à l'accès API sur votre compte, ces requêtes répondent 409 avec code: not_available.
Champs du lead :
| Champ | Description |
|---|---|
id, stage | identifiant et étape |
clientType | buyer ou seller |
country, objectId, objectIds | pays et annonces concernées par la demande |
budget | min, max, currency |
answers | les réponses du client : budget, timeline, payment |
qualScore, qualBand | score de qualité du lead |
clientInitial | la première lettre du nom du client |
offer | votre offre ouverte : id, wave, offeredAt, deadline |
contactDeadline, meetingDeadline | date limite pour contacter et pour rencontrer le client |
deal, reservation, dealObjects | données de la transaction et de la réservation |
client | name et phone du client - uniquement une fois le lead attribué et le contact révélé |
brokerId | le courtier dont la vue est affichée |
fee | la commission de la plateforme sur ce lead pour vous : none, percent (ce pourcentage de la commission que vous percevez, dans percent) ou contract (selon accord) ; jamais de montants |
Étapes (stage) : new, offered, intro, match, contact, meeting_scheduled, meeting_held, contract, deal, closed, lost.
Vos étapes avec un lead
POST /match/leads/{id}/events - uniquement pour un lead qui vous est attribué. Le module vérifie que l'étape est autorisée à l'étape actuelle.
event | Champs | Signification |
|---|---|---|
FIRST_CONTACT | channel : phone (par défaut) ou messenger | vous avez joint le client |
RESERVATION | amount, currency (3 lettres), date ; documentFileId - facultatif | le client a versé une réservation |
STAGE_ROLLBACK | reasonCode : client_withdrew, seller_withdrew, financing_failed, documents, other ; text - jusqu'à 500 | ramener le lead à l'étape précédente |
LEAD_LOST | reasonCode : client_refused, client_unreachable, bought_elsewhere, not_target, other ; text. Un autre motif - 400 | le lead est perdu |
DEAL_CLOSED | objectId, amount, currency, date, documentFileId ; commissionReceived, commissionCurrency - facultatifs | la transaction est conclue |
documentFileId - l'identifiant d'un fichier téléversé avec POST /uploads (Fichiers). Un reasonCode hors de sa liste donne 400 ; pour LEAD_LOST avec other, le text est obligatoire (400 sans lui) ; pour STAGE_ROLLBACK, le text n'est conservé qu'avec other.
curl -X POST https://developers.grem.capital/api/v1/match/leads/LEAD_ID/events \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fc-LEAD_ID-1" \
-d '{"event":"FIRST_CONTACT","channel":"phone"}'
Réponse : lead - le lead après la transition, replay: true - lorsqu'il s'agit d'une nouvelle tentative avec la même Idempotency-Key. Les étapes du client ne passent pas par l'API. Ici, Idempotency-Key fait 8 à 128 caractères : lettres, chiffres, _ . : - ; tout autre format donne 400 validation.
Les refus arrivent en 409 avec title: business_rule et le motif dans code :
| Motif | code |
|---|---|
| l'étape n'est pas disponible à l'étape actuelle | invalid_transition |
| un événement du client, les courtiers ne l'envoient pas | client_event_rejected |
| le module n'est pas encore ouvert à l'API | not_available |
Événements
match.lead.offered, match.lead.offer_closed, match.lead.matched, match.lead.updated, match.lead.unassigned - voir Webhooks. Les événements ne contiennent jamais les coordonnées du client.