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.

Basis-URL — https://api.youraiconnector.com/v1
Authentifizierung — Ihr API-Schlüssel (siehe Authentifizierung)
Fehler & Paginierung — siehe Fehler & Paginierung

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",
  "notes": "Prefers a call after 5pm.",
  "stage": "stage-2",
  "pipeline_id": "default",
  "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 mit GET /pipelines (siehe Pipelines weiter unten). Phasen-IDs sind über alle Ihre Pipelines hinweg eindeutig, daher wird pipeline_id von der Phase abgeleitet und ist schreibgeschützt: default ist Ihre Haupt-Pipeline, und sie ist null, wenn die Phase nicht mehr existiert. Zeitstempel entsprechen ISO 8601.

Ein Deal speichert nur die oben gezeigten Felder. Wenn Sie einen erstellen oder aktualisieren, wird jedes andere Feld mit einem 400 abgelehnt, das es benennt, sodass nichts, was Sie senden, stillschweigend verloren geht. Speichern Sie zusätzliche Daten in den benutzerdefinierten Feldern des verknüpften Kontakts.

Deals auflisten

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

Abfrageparameter (alle optional): stage (eine Phasen-ID), pipeline_id (nur die Deals in dieser Pipeline), contact_id, limit (Standard 50, max. 200), cursor (von der next_cursor der vorherigen Seite).

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.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.youraiconnector.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.youraiconnector.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.youraiconnector.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, notes, value, stage, status, priority, contact_id, …). value muss eine Zahl sein.

curl -X PUT "https://api.youraiconnector.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.youraiconnector.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.youraiconnector.com/v1/deals/deal_abc123?apiKey=YOUR_API_KEY"

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

Pipelines

Jedes Konto hat eine Haupt-Pipeline (id: "default"); Sie können bis zu neun weitere hinzufügen, jede mit ihren eigenen Phasen. Phasen-IDs und Trigger-Tags müssen über alle Pipelines des Kontos hinweg eindeutig sein, und jede Pipeline kann eine Phase als won und eine als lost markieren.

Pipelines auflisten

GET /pipelines — jede Pipeline, beginnend mit der Haupt-Pipeline, jeweils mit den nach Position sortierten Phasen.

curl "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY"

Antwort (200):

{
  "success": true,
  "data": {
    "pipelines": [
      {
        "id": "default",
        "name": "Sales",
        "position": 0,
        "is_default": true,
        "settings": { "sync_stage_tags": false },
        "stages": [
          { "id": "stage-1", "name": "New lead", "color": "#3B82F6", "position": 0, "trigger_tag": null },
          { "id": "won", "name": "Won", "color": "#10B981", "position": 1, "outcome": "won" }
        ]
      }
    ]
  }
}

Pipeline erstellen

POST /pipelines — Body { "id"?, "name", "stages"?, "settings"? }. Lassen Sie id weg, damit eine generiert wird. Jede Phase verwendet dieselben Felder wie der Phasen-Dialog: id, name, color, position, optional trigger_tag (ein Tag-Pfad, users/{uid}/tags/{tagId}), default_value, auto_move_after_days + auto_move_to_stage (eine Phase derselben Pipeline) und outcome ("won" oder "lost").

curl -X POST "https://api.youraiconnector.com/v1/pipelines?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reviews",
    "name": "Review requests",
    "stages": [
      { "id": "rv_asked", "name": "Asked", "color": "#3B82F6", "position": 0 },
      { "id": "rv_done", "name": "Review posted", "color": "#10B981", "position": 1, "outcome": "won" }
    ]
  }'

Antwort (201): { "success": true, "data": { "pipeline": { ... } } }. Eine Phasen-ID oder ein Trigger-Tag, das bereits von einer anderen Pipeline verwendet wird, ist ein 400, das diese Pipeline benennt; eine ID, die bereits existiert, ist ein 409.

Pipeline aktualisieren

PUT /pipelines/{pipelineId} — Body { "name"?, "stages"?, "settings"? }. stages ersetzt die gesamte Liste, wie im Phasen-Dialog. Verwenden Sie default für die Haupt-Pipeline. Die Pipeline-ID selbst kann nicht geändert werden.

Pipeline löschen

DELETE /pipelines/{pipelineId} — entfernt eine zusätzliche Pipeline (die Haupt-Pipeline kann nicht gelöscht werden). Wenn sich noch Deals in ihren Phasen befinden, antwortet der Aufruf mit 409 und deal_count; fügen Sie ?delete_deals=true hinzu, um diese Deals zusammen mit der Pipeline zu löschen. Dies kann nicht rückgängig gemacht werden.

Antwort (204).

Nächste Schritte

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

Deals-API #

Das Deal-Objekt #

Deals auflisten #

Einen Deal abrufen #

Einen Deal erstellen #

Einen Deal aktualisieren #

Einen Deal in eine andere Phase verschieben #

Einen Deal löschen #

Pipelines #

Pipelines auflisten #

Pipeline erstellen #

Pipeline aktualisieren #

Pipeline löschen #

Nächste Schritte #