DM Champ Docs

Deals-API

Ein Deal ist eine Verkaufschance auf Ihrem Sales Pipeline-Board – bestehend aus einem Titel, einem Wert, der Phase, in der er sich befindet, sowie optional dem zugehörigen Kontakt und dem zugewiesenen Teammitglied. Dieser Leitfaden behandelt das Lesen und Verwalten von Deals über die API.

Alle nachstehenden Beispiele zeigen die ?apiKey=-Abfrageform in cURL und den X-API-Key-Header in JavaScript und Python – beides funktioniert an jedem Endpunkt.

Das Deal-Objekt 

{
  "id": "deal_abc123",
  "title": "Annual plan – Jane's Clinic",
  "description": "Asked for pricing on the annual plan.",
  "company": "Jane's Clinic",
  "stage": "stage-2",
  "value": 4800,
  "probability": 60,
  "priority": "high",
  "status": "open",
  "source": "whatsapp",
  "position": 0,
  "contact_id": "ctc_9f8e7d",
  "assigned_to": "usr_4a2b",
  "tags": ["clinic"],
  "close_date": "2026-10-01T00:00:00.000Z",
  "created_at": "2026-09-05T09:12:00.000Z",
  "updated_at": "2026-09-05T09:40:00.000Z",
  "stage_entered_at": "2026-09-05T09:40:00.000Z"
}

stage ist die ID einer Ihrer Pipeline-Phasen – lesen Sie diese aus Ihren Pipeline-Einstellungen (GET /users/me/pipeline-settings) aus. Zeitstempel entsprechen ISO 8601.

Deals auflisten

GET /deals – gibt die Deals Ihres Kontos zurück, beginnend mit dem neuesten.

Abfrageparameter (alle optional): stage (eine Phasen-ID), contact_id, limit (Standard 50, max. 200), cursor (von der next_cursor der vorherigen Seite).

cURL

curl "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY&stage=stage-2&limit=50"

JavaScript

const res = await fetch("https://api.dmchamp.com/v1/deals?stage=stage-2&limit=50", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { deals, next_cursor } = await res.json();

Python

res = requests.get(
    "https://api.dmchamp.com/v1/deals",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"stage": "stage-2", "limit": 50},
)
deals = res.json()["deals"]

Antwort (200)

{ "success": true, "deals": [{ "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." }], "next_cursor": null }

Einen Deal abrufen

GET /deals/{dealId}

curl "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Antwort (200)

{ "success": true, "deal": { "id": "deal_abc123", "title": "Annual plan – Jane's Clinic", "...": "..." } }

Ein Deal, der nicht existiert oder zu einem anderen Konto gehört, gibt 404 zurück.

Einen Deal erstellen

POST /deals – title und stage sind erforderlich; stage muss eine der Phasen-IDs Ihrer Pipeline sein.

curl -X POST "https://api.dmchamp.com/v1/deals?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Annual plan – Jane'"'"'s Clinic", "stage": "stage-1", "value": 4800, "contact_id": "ctc_9f8e7d" }'

Antwort (201)

{ "success": true, "deal_id": "deal_abc123" }

Einen Deal aktualisieren

PUT /deals/{dealId} – senden Sie nur die Felder, die Sie ändern möchten (title, description, value, stage, status, priority, contact_id, …). value muss eine Zahl sein.

curl -X PUT "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5200, "priority": "high" }'

Antwort (200): { "success": true, "deal_id": "deal_abc123" }

Einen Deal in eine andere Phase verschieben

POST /deals/{dealId}/move — body { "new_stage_id": "stage-3", "new_position": 0 }. Die Position 0 platziert die Karte ganz oben in der Spalte.

curl -X POST "https://api.dmchamp.com/v1/deals/deal_abc123/move?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "new_stage_id": "stage-3", "new_position": 0 }'

Antwort (200): { "success": true, "deal_id": "deal_abc123", "stage": "stage-3", "position": 0 }

Einen Deal löschen

DELETE /deals/{dealId} — entfernt den Deal. Dies kann nicht rückgängig gemacht werden.

curl -X DELETE "https://api.dmchamp.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

Antwort (200): { "success": true }

Nächste Schritte

  • Verkaufspipeline — wie Phasen, Phasen-Tags und das Board funktionieren.
  • Aufgaben-API — Aufgaben können mit deal_id mit einem Deal verknüpft werden.
  • Automatisierungen — die Schritte Deals finden und Deal finden lesen dieselben Daten innerhalb eines Workflows.