Deals

ÜberblickEndpunkte

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, Deal-Datensätze zu erstellen und zu verwalten sowie Deal-Daten 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, nehmen Sie eine POST-Anfrage an /crm/v3/objects/deals vor.

Schließen Sie in Ihrer Anfrage Ihre Deal-Daten 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

Deal-Details werden in Deal-Eigenschaften gespeichert. Es gibt Standard-HubSpot-Deal-Eigenschaften, Sie können jedoch auch benutzerdefinierte Eigenschaften erstellen.

Beim Erstellen eines neuen Deals sollten Sie die folgenden Eigenschaften in Ihre Anfrage einschließen: dealname, dealstage und, wenn Sie mehrere Pipelines haben, pipeline. Wenn keine Pipeline angegeben ist, wird die Standard-Pipeline verwendet. 

Um alle verfügbaren Eigenschaften anzuzeigen, können Sie eine Liste der Deals Ihres Accounts abrufen, indem Sie eine GET-Anfrage an /crm/v3/properties/deals durchführen. Erfahren Sie mehr über die Eigenschaften-API.

Bitte beachten: Sie müssen die interne ID einer Deal-Phase 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 Deal-Phase oder -Pipeline in Ihren Deal-Pipeline-Einstellungen finden.

Um beispielsweise einen neuen Deal zu erstellen, kann Ihre Anfrage wie folgt aussehen:

///Example request body { "properties": { "amount": "1500.00", "closedate": "2019-12-07T16:50:06.678Z", "dealname": "New deal", "pipeline": "default", "dealstage": "contractsent", "hubspot_owner_id": "910901" } }

Zuordnungen

Beim Erstellen eines neuen Deals können Sie den Deal auch bestehenden Datensätzen oder Aktivitäten zuordnen. Schließen Sie im associations-Objekt die folgenden Felder ein:

Use this table to describe parameters / fields
ParameterDescription
toObjectId

Die ID des Datensatzes oder der Aktivität, dem oder der der Deal zugeordnet werden soll.

associationTypeId

Eine eindeutige ID, die den Zuordnungstyp zwischen dem Deal und dem anderen Objekt oder der anderen Aktivität angibt. Standardzuordnungstypen sind hier aufgeführt, oder Sie können den Wert abrufen, indem Sie eine GET-Anfrage an /crm/v4/associations/{fromObjectType}/{toObjectType}/labels durchführen. Erfahren Sie mehr über die Zuordnungen-API.

Sie können auch das label-Feld hinzufügen, um ein definiertes Zuordnungslabel zuzuweisen, das die Zuordnung beschreibt. Erfahren Sie mehr über das Zuordnen von Datensätzen über die Zuordnungen-API.

Um beispielsweise einen neuen Deal mit einem bestehenden Kontakt und Unternehmen zu verknüpfen, müsste Ihre Anfrage wie folgt aussehen:

///Example request body { "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 } ] }] }

Deals abrufen

Sie können Deals einzeln oder in Batches 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:
Use this table to describe parameters / fields
ParameterDescription
properties
Eine 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.
propertiesWithHistory

Eine 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.

associations

Eine 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.

Für den Batch-Leseendpunkt können Sie auch den optionalen idProperty-Parameter verwenden, um Deals anhand einer benutzerdefinierten „Eindeutige ID“-Eigenschaft abzurufen. Standardmäßig beziehen sich die id-Werte in der Anfrage auf die Datensatz-ID (hs_object_id), sodass der idProperty-Parameter beim Abrufen nach Datensatz-ID nicht erforderlich ist. Um eine benutzerdefinierte „Eindeutiger Wert“-Eigenschaft zum Abrufen von Deals zu verwenden, müssen Sie den idProperty-Parameter einschließen.

Um beispielsweise einen Batch von Deals abzurufen, könnte Ihre Anfrage wie folgt aussehen:

///Example request body with record ID { "properties": [ "dealname", "dealstage", "pipeline" ], "inputs": [ { "id": "7891023" }, { "id": "987654" } ] }
///Example request body with a unique value property { "properties": [ "dealname", "dealstage", "pipeline" ], "idProperty": "uniqueordernumber", "inputs": [ { "id": "0001111" }, { "id": "0001112" } ] }

Um Deals mit aktuellen und historischen Werten für eine Eigenschaft abzurufen, könnte Ihre Anfrage wie folgt aussehen:

///Example request body with record ID (current and historical values) { "propertiesWithHistory": [ "dealstage" ], "inputs": [ { "id": "7891023" }, { "id": "987654" } ] }

Deals aktualisieren

Sie können Deals einzeln oder mehrere gleichzeitig aktualisieren. Für bestehende Deals ist die Deal-ID ein eindeutiger Wert, den Sie verwenden können, um den Deal über die API zu aktualisieren.

Um einen einzelnen Deal anhand seiner Deal-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.

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 Verknüpfung 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 Deal-Datensatz anpinnen

Sie können eine Aktivität über eine API an einen Deal anpinnen, indem Sie das hs_pinned_engagement_id-Feld in Ihre Anfrage aufnehmen. Geben Sie 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:

///Example request body PATCH /crm/v3/objects/deals/{dealId} { "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:

///Example request body POST /crm/v3/objects/deals { "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.

Erfahren Sie mehr über das gleichzeitige Löschen von mehreren Deals, indem Sie oben in diesem Artikel auf die Registerkarte Endpunkte klicken.

War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.