Leads über die API

Zuletzt aktualisiert: 2026-10-035 Min. Lesezeit

Dieser Abschnitt gibt programmatischen Zugriff auf Ihre eigenen CRM-Leads: Eine Website oder ein externes Formular kann Anfragen direkt ins Kabinett senden, und Ihr System kann sie lesen und durch die Status bewegen.

Basisadresse: https://developers.grem.capital/api/v1.

Leads sind privat. Anders als beim öffentlichen Objektkatalog gibt es ohne den passenden Bereich keinen Zugriff: Lesen braucht leads:read, Änderungen leads:write. Sie sehen nur Leads, bei denen Sie Absender oder Empfänger sind. Anfragen werden nicht berechnet.

Liste

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

Filter: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Archivierte Leads stehen nicht in der normalen Liste - fügen Sie archived=true hinzu. pool=true (nur Agenturschlüssel) - die Leads im gemeinsamen Pool der Agentur; ein persönlicher Schlüssel ignoriert es.

limit (1-50, Standard 20) und page (ab 1) außerhalb des Bereichs werden in ihn gesetzt, nicht abgelehnt. Andere ungültige Werte eines bekannten Parameters (unbekannter Aufzählungswert, nicht ganzzahliges page, ungültiges Datum in from oder to) werden mit 400 validation und dem Feldnamen abgelehnt.

Ein Lead

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

expand fügt den Status- und Aktionsverlauf (history) und die angehängten Dokumente (documents) hinzu.

Form eines Leads

id, status, type, priority, source, tags, isArchived; type - buy, rent, viewing, sell, contract, transfer oder user
createdAt, updatedAt, lastActivityAt
customer - Name, Land, Messenger und ein Block contact (phone, email, messengerHandle, profileUrl)
budget - { value, currency }
intent - Stadt, Bezirke, Geschäftsart und Absicht des Kunden
comments - der Kommentar des Kunden und Ihr eigener, getrennt
object - das Objekt, um das es in der Anfrage geht
agency - nur bei Agentur-Leads: die Agentur-ID und ob der Lead im gemeinsamen Pool liegt

Kontakte anderer Makler, interne Bewertungen und Dienstkennzeichen werden nie zurückgegeben.

Eine Anfrage übermitteln

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": "[email protected]" }
    },
    "type": "buy",
    "budget": { "value": 120000, "currency": "USD" },
    "intent": { "targetCity": "Kyiv", "leadIntent": "buyer" },
    "comments": "Sucht eine 2-Zimmer-Wohnung nahe der Metro",
    "priority": "warm",
    "consent": true
  }'

Pflicht: customer.name und mindestens ein Kontaktweg in customer.contact. type - buy (Standard) oder rent. priority - hot, warm oder cold. Fügen Sie objectId hinzu, wenn es um ein bestimmtes Objekt geht, und bis zu zehn eigene tags.

Idempotency-Key schützt vor Duplikaten: Wiederholt Ihr Formular die Anfrage nach einer Zeitüberschreitung, wird der Lead nicht zweimal angelegt. Siehe Idempotenz.

pool: true sendet die Anfrage in den gemeinsamen Verteilungspool statt in Ihr CRM. Standardmäßig kommt der Lead zu Ihnen.

Jeder über die API angelegte Lead ist im Kabinett mit der Quelle «API» gekennzeichnet, damit Sie ihn unterscheiden können.

Einen Lead ändern

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

Sie können Status, Priorität, Tags und Ihren eigenen Kommentar ändern. Ein Feld genügt. Status: new, in progress, processing, agreement, closed, not target, failed. Es gelten die Regeln des Kabinetts: ein Lead mit Objekt wird über die Finalisierung im Kabinett geschlossen (code: finalize), ein Lead, der auf die Provision wartet, behält seinen Status (fee_pending), ein abgeschlossener Deal mit Vertrag ändert sich nur im Kabinett (closed) - 422 mit dem Grund in code. Weitere Gründe: sender (Sie haben den Lead weitergegeben - der Empfänger betreut ihn), module (ein Swipe-Match-Lead, sein Status folgt dem Modul), agreement, network_readonly, forbidden.

Einen Lead entfernen

DELETE /leads/{id}

Der Lead wird archiviert, nicht gelöscht: Er verschwindet aus der normalen Liste, bleibt aber mit ?archived=true verfügbar. Ein Lead mit aktivem Vertrag oder Finalisierungsvereinbarung, ein geschlossener Lead mit Objekt ohne Finalisierung und ein Lead, der auf die Provision wartet, werden nicht archiviert: 422 mit code contract_active, agreement, finalize oder fee_pending.

Objekte für einen Lead

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

Liefert Objekte, die zur Anfrage des Kunden passen: Typ, Stadt und Budget stammen aus dem Lead selbst oder aus dem verknüpften Objekt. Kostenlos.

Agentur-Pool

Agenturschlüssel haben zwei Pool-Aktionen:

POST /leads/{id}/claim               einen Lead aus dem Pool nehmen
POST /leads/{id}/claim?assignTo=...  einem Teammitglied zuweisen
POST /leads/{id}/return-to-pool      einen Lead in den Pool zurückgeben

Nehmen: Standardmäßig geht der Lead an den Agenturinhaber; assignTo (Mitglieds-ID) dürfen der Inhaber oder ein Manager übergeben.
In den Pool zurückgeben: ab Manager oder der Agent, dem der Lead zugewiesen ist. Optionaler Body: {"reason": "..."}. Ein Lead, den die Pool-Regeln archiviert haben - 422 mit code: pool_archived: Stellen Sie ihn zuerst im Kabinett wieder her.
Ein persönlicher Schlüssel oder eine zu niedrige Rolle - 403 mit title: forbidden; einen Lead nehmen, der nicht mehr im Pool ist - 404.
Beide Aktionen senden ein Ereignis lead.updated.

Änderungen verfolgen

Statt die Liste abzufragen, abonnieren Sie lead.created und lead.updated - siehe Webhooks. Das Ereignis enthält keine personenbezogenen Daten: Es sagt nur, welcher Lead sich geändert hat; die Karte lesen Sie mit einer eigenen Anfrage.