Leads über die API

Zuletzt aktualisiert: 2026-09-074 Min. Lesezeit

Dieser Bereich gibt programmgesteuerten Zugang zu Ihren eigenen Leads im CRM: Eine Website oder ein fremdes Formular kann Anfragen direkt ins Kabinett schicken, und Ihr System kann sie lesen und durch die Zustände führen.

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

Leads sind privat. Anders als beim öffentlichen Katalog der Objekte gibt es hier keinen Zugang ohne Geltungsbereich: Lesen braucht leads:read, Änderungen brauchen leads:write. Sie sehen immer nur Leads, bei denen Sie Absender oder Empfänger sind.

Die Liste

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

Parameter der Filter: status, type, priority, source, role, archived, pool, from, to, page, limit, sort. Archivierte Leads bleiben in der gewöhnlichen Liste außen vor - ergänzen Sie archived=true.

Ein einzelner Lead

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

expand fügt die Chronik der Zustände und Handlungen (history) sowie die Liste der angehängten Dokumente (documents) hinzu.

Der Aufbau eines Leads

id, status, type, priority, source, tags, isArchived
createdAt, updatedAt, lastActivityAt
customer - Name, Land, Messenger und ein Block contact (phone, email, messengerHandle, profileUrl)
budget - { value, currency }
intent - Stadt, Stadtviertel, Art des Geschäfts und was der Kunde sucht
comments - der Kommentar des Kunden und Ihr eigener, getrennt
object - das Inserat, auf das sich die Anfrage bezieht
deadline, reminder
agency - nur bei Leads einer Agentur: die Kennung der Agentur und ob der Lead im gemeinsamen Pool liegt

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

Eine Anfrage von außen schicken

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 two-room flat near the metro",
    "priority": "warm",
    "consent": true
  }'

Pflicht: customer.name und mindestens ein Weg zur Kontaktaufnahme in customer.contact. type ist buy (Vorgabe) oder rent. priority ist hot, warm oder cold. Sie können eine objectId ergänzen, wenn es um ein bestimmtes Inserat geht, und in tags bis zu zehn eigene Bezeichnungen.

Der Kopf Idempotency-Key bewahrt Sie vor Dopplungen: Hat Ihr Formular nach einer Zeitüberschreitung wiederholt, entsteht der Lead nicht zweimal. Siehe Idempotenz.

Die Marke pool: true leitet die Anfrage zur Verteilung in den gemeinsamen Pool statt in Ihr eigenes CRM. Standardmäßig landet der Lead bei Ihnen.

Jeder über die API angelegte Lead trägt im Kabinett die Quelle «API» und hebt sich damit von den übrigen ab.

Einen Lead ändern

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

Ändern lassen sich Zustand, Priorität, Bezeichnungen und Ihr eigener Kommentar. Ein Feld genügt. Verfügbare Zustände: new, in progress, processing, agreement, closed, not target, failed.

Einen Lead weglegen

DELETE /leads/{id}

Das archiviert, statt zu löschen: Der Lead fällt aus der gewöhnlichen Liste, bleibt aber über ?archived=true erreichbar.

Passende Objekte zu einem Lead

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

Gibt Inserate zurück, die auf die Anfrage des Kunden antworten: Art, Stadt und Budget kommen aus dem Lead selbst oder aus dem angehängten Inserat. Der Aufruf ist kostenlos.

Der Pool der Agentur

Schlüssel einer Agentur bekommen zwei Handlungen am Pool:

POST /leads/{id}/claim               einen Lead aus dem Pool für sich nehmen
POST /leads/{id}/claim?assignTo=…    den Lead einem Mitglied des Teams zuweisen
POST /leads/{id}/return-to-pool      den Lead in den Pool zurückgeben

Beides braucht eine Rolle in der Agentur, die das Verteilen von Leads erlaubt. Ein persönlicher Schlüssel wird abgewiesen, und einen bereits genommenen Lead zu übernehmen gibt 409 zurück.

Änderungen verfolgen

Statt die Liste abzufragen, abonnieren Sie die Ereignisse lead.created und lead.updated - siehe Webhooks. Das Ereignis selbst trägt keine persönlichen Daten: Es sagt nur, welcher Lead sich geändert hat, die Karte lesen Sie in einer eigenen Anfrage.