Letzte Änderung: 22. August 2025

Run in Postman

 Verwenden Sie die Anrufinteraktion-API, um Anrufe in CRM-Datensätzen und auf der Indexseite für Anrufe zu protokollieren und zu verwalten. Sie können Anrufe entweder in HubSpot oder über die Anrufe-API protokollieren. Im Folgenden erfahren Sie, wie Sie Anrufe über die API verwalten können. Zur Ansicht aller verfügbaren Endpunkte und deren Anforderungen lesen Sie bitte die Referenzdokumentation.

​
Eine Anrufinteraktion erstellen

Um eine Anrufinteraktion zu erstellen, führen Sie eine POST-Anfrage an /crm/v3/objects/calls durch. Fügen Sie im Anfragetext Anrufdetails in einem properties-Objekt hinzu. Sie können auch ein associations-Objekt hinzufügen, um Ihren neuen Anruf einem vorhandenen Datensatz (z. B. Kontakten, Unternehmen) zuzuordnen.

​
Eigenschaften

Nachfolgend finden Sie eine Liste der HubSpot-Standardanfrufeigenschaften, die Sie in das Eigenschaftsobjekt aufnehmen können. Sie können mit der Eigenschaften-API auch benutzerdefinierte Eigenschaften erstellen.
FeldBeschreibung
hs_timestampErforderlich. Dieses Feld markiert den Zeitpunkt der Erstellung des Anrufs und bestimmt, wo Sie den Anruf in der Datensatzchronik finden. Sie können entweder einen Unix-Zeitstempel im Millisekunden- oder UTC-Format verwenden.
hs_call_bodyDie Beschreibung des Anrufs, einschließlich aller Anmerkungen, die Sie hinzufügen möchten.
hs_call_callee_object_idDie ID des HubSpot-Datensatzes, der dem Anruf zugeordnet ist. Dies ist der Empfänger des Anrufs für OUTBOUND-Anrufe oder der Wähler des Anrufs für INBOUND-Anrufe.
hs_call_callee_object_typeDie Art des Objekts, zu dem der zugeordnete Datensatz des Anrufs gehört (gibt z. B. an, ob der Datensatz ein Kontakt oder ein Unternehmen ist). Dies ist das Objekt des Empfängers für OUTBOUND-Anrufe oder das Objekt des Wählers für INBOUND-Anrufe.
hs_call_directionDie Richtung des Anrufs aus der Perspektive des HubSpot-Benutzers. Wenn der Benutzer der Anrufempfänger ist, sollte die Richtung auf INBOUND festgelegt werden. Wenn der Benutzer den Anruf initiiert hat, sollte die Richtung auf OUTBOUND festgelegt werden.
hs_call_dispositionDas Ergebnis des Anrufs. Um die Anrufdisposition einzustellen, müssen Sie den internen GUID-Wert verwenden. Wenn für Ihren Account benutzerdefinierte Anrufergebnisse eingerichtet sind, können Sie deren Dispositions-GUIDs mithilfe dieser API finden. Die standardmäßigen HubSpot-Ergebnislabels und ihre internen Werte sind:
  • Besetzt: 9d9162e7-6cf3-4944-bf63-4dff82258764
  • Verbunden: f240bbac-87c9-4f6e-bf70-924b57d47db7
  • Live-Nachricht hinterlassen: a4c4c377-d246-4b32-a13b-75a56a4cd0ff
  • Voicemail hinterlassen: b2cf5968-551e-4856-9783-52b3da59a7d0
  • Keine Antwort: 73a0d17f-1163-4015-bdd5-ec830791da20
  • Falsche Nummer: 17b47fee-58de-441e-a44c-c6300d46f273
hs_call_durationDie Dauer des Anrufs in Millisekunden.
hs_call_from_numberDie Telefonnummer, von der aus der Anruf getätigt wurde.
hs_call_recording_urlDie URL, die die Anrufaufzeichnung speichert. URLS zu .mp3- oder .wav-Dateien können in CRM-Datensätzen wiedergegeben werden. Nur HTTPS, sichere URLs werden akzeptiert.
hs_call_statusDer Status des Anrufs. Die Status sind BUSY, CALLING_CRM_USER, CANCELED, COMPLETED, CONNECTING, FAILED, IN_PROGRESS, NO_ANSWER, QUEUED und RINGING.
hs_call_titleDer Titel des Anrufs.
hs_call_sourceDie Quelle des Anrufs. Diese ist nicht erforderlich, aber sie ist notwendig, um die Aufnahme- und Transkriptionspipeline zu nutzen. Wenn die Eigenschaft festgelegt wird, muss sie auf INTEGRATIONS_PLATFORM festgelegt werden.
hs_call_to_numberDie Telefonnummer, die den Anruf erhalten hat.
hubspot_owner_idDie ID des zuständigen Mitarbeiters, der dem Anruf zugeordnet ist. Dieses Feld bestimmt den Benutzer, der in der Datensatzchronik als Anrufersteller aufgeführt ist.
hs_activity_typeDer Typ von Anruf Die Optionen basieren auf den in Ihrem HubSpot-Account festgelegten Anruftypen.
hs_attachment_idsDie IDs der Anhänge des Anrufs. Mehrere Anhang-IDs sind durch ein Semikolon getrennt.

​
Zuordnungen

Um einen Anruf zu erstellen und bestehenden Datensätzen zuzuordnen, schließen Sie ein associations-Objekt in Ihre Anfrage ein. Um beispielsweise einen Anruf zu erstellen und ihn einem Kontakt und einem Ticket zuzuordnen, könnte Ihr Anfragetext wie folgt aussehen: 
// Example request body
{
  "properties": {
    "hs_timestamp": "2021-03-17T01:32:44.872Z",
    "hs_call_title": "Support call",
    "hubspot_owner_id": "11349275740",
    "hs_call_body": "Resolved issue",
    "hs_call_duration": "3800",
    "hs_call_from_number": "(857) 829 5489",
    "hs_call_to_number": "(509) 999 9999",
    "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22",
    "hs_call_status": "COMPLETED"
  },
  "associations": [
    {
      "to": {
        "id": 500
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 194
        }
      ]
    },
    {
      "to": {
        "id": 1234
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 220
        }
      ]
    }
  ]
}
Im associations-Objekt sollten Sie Folgendes einschließen:
FeldBeschreibung
toDer Datensatz, den Sie dem Anruf zuordnen möchten, angegeben durch seinen eindeutigen id-Wert.
typesDer Typ der Zuordnung zwischen Anruf und Datensatz. 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.
Weitere Informationen zur Batch-Erstellung von Anrufen finden Sie in der Referenzdokumentation.

​
Anrufe abrufen

Sie können Anrufe einzeln oder mehrere gleichzeitig abrufen. Weitere Informationen zum Batch-Abruf finden Sie in der Referenzdokumentation. Um einen einzelnen Anruf anhand seiner Anruf-ID abzurufen, führen Sie eine GET-Anfrage an /crm/v3/objects/calls/{callId} durch. Sie können die folgenden Parameter in die Anfrage-URL einschließen:
ParameterBeschreibung
propertiesEine durch Kommas getrennte Liste der Eigenschaften, die zurückgegeben werden sollen.
associationsEine durch Kommas getrennte Liste von Objekttypen, 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 eine Liste aller Anrufe anzufordern, führen Sie eine GET-Anfrage an /crm/v3/objects/calls durch. Sie können die folgenden Parameter in die Anfrage-URL einschließen:
ParameterBeschreibung
limitDie maximale Anzahl an Ergebnissen, die pro Seite angezeigt werden können.
propertiesEine durch Kommas getrennte Liste der Eigenschaften, die zurückgegeben werden sollen.
Wenn Sie eine erfolgreiche Anfrage stellen, enthält die Antwort die callId, mit der Sie den Anruf abrufen, aktualisieren und löschen können.

​
Voicemails vs. aufgezeichnete Anrufe identifizieren

Für aufgezeichnete Anrufe und Voicemails wird eine Aufzeichnung in der hs_call_recording_url-Eigenschaft gespeichert. Wenn Ihr Account Zugriff auf Inbound-Calling hat, schließen Sie, um zwischen abgeschlossenen bzw. aufgezeichneten Anrufen und eingehenden Anrufen mit einer Voicemail zu unterscheiden, die folgenden Eigenschaften in Ihre Anfrage ein: hs_call_status und hs_call_has_voicemail. Wenn ein Anruf eine Voicemail hat, ist der hs_call_status-Wert missed und der hs_call_has_voicemail-Wert ist true. Der hs_call_has_voicemail-Wert ist false für einen eingehenden Anruf, bei dem keine Voicemail hinterlassen wurde, oder null, wenn der Anruf einen anderen Status als „verpasst“ hat.

​
Anrufe aktualisieren

Sie können Anrufe einzeln oder mehrere gleichzeitig aktualisieren. Um einen einzelnen Anruf anhand seiner Anruf-ID zu aktualisieren, führen Sie eine PATCH-Anfrage an /crm/v3/objects/calls/{callId} durch. Fügen Sie im Anfragetext die Anrufeigenschaften ein, die Sie aktualisieren möchten: 
//Example PATCH request to https://api.hubspot.com/crm/v3/objects/calls/{callID}
{
  "properties": {
    "hs_timestamp": "2021-03-17T01:32:44.872Z",
    "hs_call_title": "Discovery call",
    "hubspot_owner_id": "11349275740",
    "hs_call_body": " Decision maker out, will call back tomorrow",
    "hs_call_duration": "3800",
    "hs_call_from_number": "(857) 829 5489",
    "hs_call_to_number": "(509) 999 9999",
    "hs_call_recording_url": "https://api.twilio.com/2010-04-01/Accounts/AC890b8e6fbe0d989bb9158e26046a8dde/Recordings/RE3079ac919116b2d22",
    "hs_call_status": "COMPLETED"
  }
}'
HubSpot ignoriert Werte für schreibgeschützte und nicht vorhandene Eigenschaften. Um einen Eigenschaftswert zu löschen, übergeben Sie eine leere Zeichenfolge für die Eigenschaft im Anfragetext. Weitere Informationen zur Batch-Aktualisierung finden Sie in der Referenzdokumentation.

​
Vorhandene Anrufe zu Datensätzen zuordnen

Um einen Anruf Datensätzen zuzuordnen, z. B. einem Kontakt und seinen zugeordneten Unternehmen, führen Sie eine PUT-Anfrage an /crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId} durch. Die Anfrage-URL enthält die folgenden Felder:
FeldBeschreibung
callIdDie ID des Anrufs.
toObjectTypeDer Typ des Objekts, dem Sie den Anruf zuordnen möchten (z. B. Kontakt oder Unternehmen)
toObjectIdDie ID des Datensatzes, dem Sie den Anruf zuordnen möchten.
associationTypeIdEine eindeutige ID, die den Zuordnungstyp zwischen dem Anruf und dem anderen Objekt angibt. Die ID kann numerisch oder in Snake-Case (z. B. call_to_contact) dargestellt werden. Sie können den Wert über die Zuordnungen-API abrufen.
Ihre Anfrage-URL könnte beispielsweise wie folgt aussehen: https://api.hubspot.com/crm/v3/objects/calls/17591596434/associations/contact/104901/194

​
Eine Zuordnung entfernen

Um eine Zuordnung zwischen einem Anruf und einem Datensatz zu entfernen, führen Sie eine DELETE-Anfrage an dieselbe URL wie oben durch: /crm/v3/objects/calls/{callId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}

​
Einen Anruf in einem Datensatz anpinnen

Sie können einen Anruf in einem Datensatz anpinnen, damit er oben in der Chronik des Datensatzes bleibt. Der Anruf muss bereits vor dem Anpinnen dem Datensatz zugeordnet sein, und Sie können nur eine Aktivität pro Datensatz anpinnen. Um einen Anruf anzupinnen, fügen Sie die id des Anrufs in das hs_pinned_engagement_id-Feld ein, wenn Sie einen Datensatz über die Objekt-APIs erstellen oder aktualisieren. Erfahren Sie mehr über das Verwenden der Unternehmen-, Kontakte-, Deals-, Tickets- und Benutzerdefinierte Objekte-APIs.

​
Anrufe löschen

Sie können Anrufe einzeln oder mehrere gleichzeitig löschen, wodurch der Anruf dem Papierkorb in HubSpot hinzugefügt wird. Sie können später den Anruf über die Datensatzchronik wiederherstellen. Um einen einzelnen Anruf anhand seiner Anruf-ID zu löschen, führen Sie eine DELETE-Anfrage an /crm/v3/objects/calls/{callId} durch. Weitere Informationen zum Löschen von Anrufen finden Sie in der Referenzdokumentation.