Letzte Änderung: 22. August 2025

Run in Postman

 In HubSpot stehen Deals für Transaktionen mit Kontakten oder Unternehmen. Deals werden während Ihres Vertriebsprozesses über Pipeline-Phasen nachverfolgt, bis sie gewonnen oder verloren werden. Die Deals-Endpunkte ermöglichen es Ihnen, Dealdatensätze zu erstellen und zu verwalten sowie Dealdaten zwischen HubSpot und anderen Systemen zu synchronisieren. Erfahren Sie mehr über Objekte, Datensätze, Eigenschaften und Zuordnungen-APIs im Leitfaden Grundlegendes zum CRM. Weitere allgemeine Informationen zu Objekten und Datensätzen in HubSpot finden Sie in diesem Artikel über das Verwalten Ihrer CRM-Datenbank.

​
Deals erstellen

Um neue Deals zu erstellen, führen Sie eine POST-Anfrage an /crm/v3/objects/deals durch. Schließen Sie im Anforderungstext Ihre Dealdaten in ein properties-Objekt ein. Sie können auch ein associations-Objekt hinzufügen, um Ihren neuen Deal vorhandenen Datensätzen (z. B. Kontakte, Unternehmen) oder Aktivitäten (z. B. Meetings, Notizen) zuzuordnen.

​
Eigenschaften

Dealdetails werden in Dealeigenschaften gespeichert. HubSpot bietet eine Reihe von Standard Dealeigenschaften, aber Sie können auch benutzerdefinierte Eigenschaften erstellen. Beim Erstellen eines neuen sollten Sie die folgenden Eigenschaften in der Anfrage einschließen: dealname, dealstage und, wenn Sie mehrere haben, pipeline. Wenn keine Pipeline angegeben ist, wird die Standard-Pipeline verwendet. Um alle verfügbaren Eigenschaften anzuzeigen, können Sie eine Liste der Dealeigenschaften Ihres Accounts abrufen, indem Sie eine GET-Anfrage an /crm/v3/properties/deals durchführen. Erfahren Sie mehr über die Eigenschaften-API.

​
Hinweis:

Sie müssen die interne ID einer Dealphase oder -pipeline verwenden, wenn Sie einen Deal über die API erstellen. Die interne ID wird auch zurückgegeben, wenn Sie Deals über die API abrufen. Sie können die interne ID einer Dealphase oder -pipeline in Ihren Dealpipeline-Einstellungen finden.
Um beispielsweise einen neuen Deal zu erstellen, kann Ihre Anfrage wie folgt aussehen: 
{
  "properties": {
    "amount": "1500.00",
    "closedate": "2019-12-07T16:50:06.678Z",
    "dealname": "New deal",
    "pipeline": "default",
    "dealstage": "contractsent",
    "hubspot_owner_id": "910901",
    "hs_all_collaborator_owner_ids": ";12345678;9101112"
  }
}

​
Zuordnungen

Beim Erstellen eines neuen Deals können Sie den Deal auch bestehenden Datensätzen oder Aktivitäten in einem associations-Objekt zuordnen. Um beispielsweise einen neuen Deal mit einem bestehenden Kontakt und Unternehmen zu verknüpfen, müsste Ihre Anfrage wie folgt aussehen: 
{
  "properties": {
    "amount": "1500.00",
    "closedate": "2019-12-07T16:50:06.678Z",
    "dealname": "New deal",
    "pipeline": "default",
    "dealstage": "contractsent",
    "hubspot_owner_id": "910901"
  },
  "associations": [
    {
      "to": {
        "id": 201
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 5
        }
      ]
    },
    {
      "to": {
        "id": 301
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 3
        }
      ]
    }
  ]
}
Im associations-Objekt sollten Sie Folgendes einschließen:
ParameterBeschreibung
toDer Datensatz oder die Aktivität, den bzw. die Sie dem Deal zuordnen möchten, angegeben durch seinen eindeutigen id-Wert.
typesDer Typ der Zuordnung zwischen Deal und Datensatz/Aktivität. Beziehen Sie die associationCategory und associationTypeId ein. Standardzuordnungstyp-IDs sind hier aufgeführt. Sie können den Wert für benutzerdefinierte Zuordnungstypen (d. h. Label) über die Zuordnungen-API abrufen.

​
Deals abrufen

Sie können Deals einzeln oder mehrere gleichzeitig aktualisieren.
  • Um einen einzelnen Deal abzurufen, führen Sie eine GET-Anfrage an /crm/v3/objects/deals/{dealId} durch.
  • Um eine Liste aller Deals anzufordern, führen Sie eine GET-Anfrage an /crm/v3/objects/deals durch.
Sie können für diese Endpunkte die folgenden Abfrageparameter in die Anfrage-URL einschließen:
ParameterBeschreibung
propertiesEine durch Kommas getrennte Liste der Eigenschaften, die in der Antwort zurückgegeben werden sollen. Wenn das angefragte Deal keinen Wert für eine Eigenschaft hat, wird er nicht in der Antwort angezeigt.
propertiesWithHistoryEine durch Kommas getrennte Liste der aktuellen und historischen Eigenschaften, die in der Antwort zurückgegeben werden sollen. Wenn das angefragte Deal keinen Wert für eine Eigenschaft hat, wird er nicht in der Antwort angezeigt.
associationsEine durch Kommas getrennte Liste von Objekten, für die zugehörige IDs abgerufen werden sollen. Alle angegebenen Zuordnungen, die nicht vorhanden sind, werden nicht in der Antwort zurückgegeben. Erfahren Sie mehr über die Zuordnungen-API
  • Um einen Batch von bestimmten Deals nach Datensatz-ID oder einer benutzerdefinierten „Eindeutige ID“-Eigenschaft abzurufen, führen Sie eine POST-Anfrage an crm/v3/objects/deals/batch/read durch.
    • Der Batch-Endpunkt kann Zuordnungen nicht abrufen. Erfahren Sie, wie Sie Zuordnungen mit der Zuordnungen-API batchweise lesen.
    • Um Deals anhand einer benutzerdefinierten „Eindeutige ID“-Eigenschaft anstelle der Deal-ID abzurufen, fügen Sie den idProperty-Parameter in den Anforderungstext ein, um den Namen der Eigenschaft anzugeben. Fügen Sie dann in das inputs-Array die Werte der Eigenschaft mit der eindeutigen ID und nicht die Deal-ID ein.
Um beispielsweise einen Batch von Deals abzurufen, könnte Ihre Anfrage wie folgt aussehen: 
{
"properties": ["dealname", "dealstage", "pipeline"],
"inputs": [
{
"id": "7891023"
},
{
"id": "987654"
}
]
}
Um Deals mit aktuellen und historischen Werten für eine bestimmte Eigenschaft abzurufen, können Sie den propertiesWithHistory-Parameter wie unten gezeigt in den Anforderungstext aufnehmen. 
{
  "propertiesWithHistory": ["dealstage"],
  "inputs": [
    {
      "id": "7891023"
    },
    {
      "id": "987654"
    }
  ]
}

​
Deals aktualisieren

Sie können Deals einzeln oder mehrere gleichzeitig aktualisieren. Bei vorhandenen Deals ist die Deal-ID ein eindeutiger Standardwert, mit dem Sie en Deal über die API aktualisieren können. Sie können Deals jedoch auch mithilfe benutzerdefinierter „Eindeutige ID“-Eigenschaften identifizieren und aktualisieren.
  • Um einen einzelnen Deal anhand seiner Datensatz-ID zu aktualisieren, führen Sie eine PATCH-Anfrage an /crm/v3/objects/deals/{dealId} durch und schließen Sie die Daten ein, die Sie aktualisieren möchten.
  • Um mehrere Deals zu aktualisieren, führen Sie eine POST-Anfrage an /crm/v3/objects/deals/batch/update durch. Fügen Sie im Anfragetext ein Array mit den IDs für die Deals und die Eigenschaften hinzu, die Sie aktualisieren möchten.

​
Bestehende Deals mit Datensätzen oder Aktivitäten verknüpfen

Um einen Deal anderen CRM-Datensätzen oder einer Aktivität zuzuordnen, führen Sie eine PUT-Anfrage an /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} durch.
Um den associationTypeId-Wert abzurufen, verweisen Sie auf diese Liste der Standardwerte oder führen Sie eine GET-Anfrage an /crm/v4/associations/{fromObjectType}/{toObjectType}/labels durch.
Erfahren Sie mehr über das Zuordnen von Datensätzen mit der Zuordnungen-API.

​
Eine Zuordnung entfernen

Um eine Zuordnung zwischen einem Deal und einem Datensatz oder einer Aktivität zu entfernen, führen Sie eine DELETE-Anfrage an die folgende URL durch: /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

​
Eine Aktivität an einen Dealdatensatz anpinnen

Sie können eine Aktivität über die API an einen Dealdatensatz anpinnen, indem Sie den hs_pinned_engagement_id-Parameter in die Anfrage aufnehmen. Geben Sie für den Wert des Parameters im Feld die ID der anzupinnenden Aktivität an, die über die Interaktionen-APIs abgerufen werden kann. Sie können eine Aktivität pro Datensatz anpinnen, und die Aktivität muss bereits vor dem Anheften mit dem Deal verknüpft sein. Um die angepinnten Aktivitäten eines Deals festzulegen oder zu aktualisieren, könnte Ihre Anfrage wie folgt aussehen: 
{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}
Sie können auch ein Deal erstellen, ihn mit einer vorhandenen Aktivität verknüpfen und die Aktivität in derselben Anfrage anpinnen. Zum Beispiel: 
{
  "properties": {
    "dealname": "New deal",
    "pipelines": "default",
    "dealstage": "contractsent",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 213
        }
      ]
    }
  ]
}

​
Deals löschen

Sie können Deals einzeln oder mehrere gleichzeitig löschen, wodurch der Deal in den Papierkorb in HubSpot verschoben wird. Sie können den Deal später in HubSpot wiederherstellen.
  • Um einen einzelnen Deal anhand seiner ID zu löschen, führen Sie eine DELETE-Anfrage an /crm/v3/objects/deals/{dealId} durch. Für diese Anfrage ist kein Anforderungstext erforderlich.
  • Um Deals batchweise zu löschen, stellen Sie eine POST Anfrage an /crm/v3/objects/deals/batch/archive. Fügen Sie im Anforderungstext die Deal-ID-Werte als id-Eingaben ein, wie im folgenden Anforderungstext gezeigt.
{
  "inputs": [
    {
      "id": "123456"
    },
    {
      "id": "7891011"
    },
    {
      "id": "12123434"
    }
  ]
}
Erfahren Sie in der Referenzdokumentation mehr über das Löschen von Deals.