FAQ

Erhalten Sie Antworten auf häufig gestellte Fragen zu den APIs von HubSpot. Bei Fragen zur CMS-Entwicklung rufen Sie deren Dokumentation auf. Wenn Sie finden nicht, wonach sie suchen, können Sie in unserem Entwickler-Forum um Hilfe bitten.

Wie kann ich Formulare mithilfe von jQuery manipulieren?

Wenn Sie Formulareingabewerte mithilfe von .val() oder .prop() manipulieren, müssen Sie ein Änderungsereignis mithilfe von change() oder trigger('change') auslösen, damit die Änderung korrekt registriert wird.

Da HubSpot-Formulare nach der DOM-Erstellung dargestellt werden, müssen Sie entweder die Manipulation auslösen, nachdem das Fenster lädt, oder die Einbettung so ändern, dass der onFormReady-Parameter verwendet wird.

Update fields when page finishes loading: $(window).load(function(){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); }); Modified embed code to update fields when form builds: hbspt.forms.create({ portalId: 'XXXXXX', formId: 'aa8b5b4a-62ac-461b-a387-XXXXXXXXXXX', onFormReady: function($form, ctx){ $('input[value="checkbox_1"]').prop('checked', true).change(); $('input[name="firstname"]').val('Brian').change(); } });

Wie sollte ich Zeitstempel für die HubSpot-APIs formatieren?

HubSpot-APIs akzeptieren zwei verschiedene Formate für Datums- und Uhrzeitwerte.

Das erste Format sind ISO 8601-formatierte Zeichenfolgen. Je nach Datentyp sind diese eines von zwei verschiedenen Formaten:

  • Für Werte, die ein bestimmtes Datum darstellen, wird das vollständige Datumsformat verwendet: JJJJ-MM-TT (z. B. 2020-02-29)
  • Für Werte, die ein bestimmtes Datum und eine bestimmte Zeit darstellen, werden die vollständigen Daten plus Stunden, Minuten, Sekunden und ein Dezimalbruch eines zweiten Formats verwendet: JJJJ-MM-TTThh:mm:ss.sTZD (z. B. 2020-02-29T03:30:17.000Z). Beachten Sie, dass alle Zeiten in UTC angezeigt werden, damit die Werte immer den UTC-Bezeichner „Z“ verwenden.

Das zweite Format sind UNIX-formatierte Zeitstempel in Millisekunden. Zeitstempelwerte werden wie in UTC-Zeit festgelegte Werte behandelt. Der Zeitstempelwert 1427997766000 wird zum Beispiel in 2. April, 2015, 2:02:46 Uhr EDT (Eastern Daylight Saving Time) oder 02. April 2015 18:02:46 UTC übersetzt.

Zeitwerte werden mit dem ISO 8601-Wert in Antworten dargestellt, die APIs akzeptieren jedoch beide Formate.

Datums- und Datetime-Eigenschaften im HubSpot CRM

HubSpot verfügt über zwei Arten von CRM-Objekteigenschaften zur Speicherung von Zeitangaben: Datum und Datetime.

Date-Eigenschaften (einschließlich in HubSpot erstellter date picker) können nur das Datum und nicht die Uhrzeit speichern. Wenn Sie Datumseigenschaftswerte festlegen, empfehlen wir, das vollständige ISO 8601-Datumsformat zu verwenden.

Beispiele:

  • 2015-05-01 würde für 1. Mai 2015 verwendet werden. Es ist zwar möglich, einen Millisekunden-Zeitstempel zu verwenden, die Werte müssen für das gewünschte Datum auf Mitternacht UTC festgelegt werden. 
  • 1430438400000 würde für 1. Mai 2015 (1. Mai 2015 00:00:00 Uhr UTC) verwendet werden.

Wenn Sie versuchen, einen Wert festzulegen, der nicht Mitternacht UTC ist, erhalten Sie einen Fehler. In HubSpot zeigen die Datumseigenschaften immer das spezifische Datum an, auf das sie festgelegt sind, unabhängig von der Einstellung zur Zeitzone des Accounts oder Benutzers.

Datetime-Eigenschaften können jede Zeit speichern, sodass jeder gültige Datums- oder Uhrzeitwert, der ein beliebiges Format verwendet, akzeptiert wird. In HubSpot werden Datetime-Eigenschaften basierend auf der Zeitzone des Benutzers angezeigt, der den Datensatz anzeigt, sodass der Wert in die lokale Zeitzone des Benutzers konvertiert wird.

Die einzige Möglichkeit, eine Datetime-Eigenschaft zu erstellen, ist mithilfe der APIs, da alle in HubSpot erstellten Datumsauswahleigenschaften als Datumseigenschaft erstellt werden. Wenn Ihre Integration bestimmte Zeiten speichern muss, empfehlen wir, mithilfe der Eigenschaftsendpunkte benutzerdefinierte Datetime-Eigenschaften für die jeweiligen CRM-Objekte zu erstellen, mit denen Ihre Integration arbeitet.


Was muss ich über API-Fehlermeldungen wissen?

Sofern nicht anders angegeben, geben die meisten HubSpot-Endpunkte eine „200 OK“-Antwort bei einem Erfolg zurück. Bei allen Endpunkten, die einen anderen Statuscode zurückgeben, wird die zurückgegebene Antwort in ihrer Dokumentation erläutert.

Darüber hinaus hat HubSpot mehrere Fehlerantworten, die häufig bei mehreren APIs auftreten:

  • 401 Unauthorized – Wird zurückgegeben, wenn die angegebene Authentifizierung ungültig ist. Weitere Informationen zur Authentifizierung von API-Anfragen finden Sie in unserer  Übersicht über die Authentifizierung.
  • 403 Forbidden – Wird zurückgegeben, wenn die Authentifizierung nicht die erforderlichen Berechtigungen hat, um auf die spezifische URL zuzugreifen. Ein OAuth-Token, das nur Content-Zugriff hat, würde eine 403-Meldung erhalten, wenn es auf die Deals-API zugreift (die Zugriff auf Kontakte erfordert).
  • 429 Too many requests – Wird zurückgegeben, wenn Ihr Account oder Ihre App über den API-Limits liegt. Hier finden Sie Vorschläge, wir Sie mit diesen Limits umgehen.
  • 502/504 Timeouts – HubSpot verfügt über Verarbeitungslimits, um zu vermeiden, dass ein einzelner Client Leistungseinbußen verursacht, und diese Antworten weisen darauf hin, dass diese Limits erreicht wurden. Sie sehen normalerweise diese Timeout-Antworten nur dann, wenn Sie eine große Anzahl von Anfragen über einen längeren Zeitraum vornehmen. Wenn Sie eine dieser Antworten erhalten, sollten Sie Ihre Anfragen für einige Sekunden pausieren und es dann erneut versuchen.

Neben diesen allgemeinen Fehlern sind die Antworten auf HubSpot-Fehler als menschenlesbare Inhalte gedacht. Die meisten Endpunkte geben keine Fehlercodes, sondern eine JSON-formatierte Antwort mit Details zum Fehler zurück. Weitere Details zu endpunktspezifischen Fehlern finden Sie auf den Dokumentationsseiten für den Endpunkt.

Hinweis: Die folgenden Felder in der Beispielantwort sollten bei jeder Fehleranalyse als optional behandelt werden. Die spezifischen enthaltenen Felder können zwischen verschiedenen APIs variieren, so dass bei der Fehleranalyse berücksichtigt werden sollte, dass bestimmte Felder in der Antwort fehlen.

{"status":"error","message":"This will be a human readable message with details about the error.","errors":[{"message":"This will be a message with additional details about the error","in":"name"}],"category":"VALIDATION_ERROR","correlationId":"a43683b0-5717-4ceb-80b4-104d02915d8c"}

Unterstützen die HubSpot-APIs COS/AJDAX-Anfragen?

In den meisten Fällen unterstützen die HubSpot-APIs keine ursprungsübergreifenden (CORS) AJAX-Anfragen. Wenn Sie die Anfrage mithilfe von JavaScript client-seitig vornehmen, würde jegliche Authentifizierung offengelegt, die Sie für die Anfrage vornehmen. Um JavaScript/AJDAX zu verwenden, müssen Sie die Anfrage (ausgenommen jeglicher Authentifizierung) an einen externen Server vornehmen, der dann die erforderliche Authentifizierung hinzufügt und Anfragen an die APIs von HubSpot serverseitig vornimmt.

Es gibt folgende Ausnahmen zu dieser Regel:


Wie validiert HubSpot E-Mail-Adressen?

Bei jedem Prozess, bei dem ein Kontaktdatensatz erstellt oder aktualisiert wird, validiert HubSpot E-Mail-Adressen. Dies umfasst die Verwendung der Kontakte-Endpunkte, um einen Kontakt sowie Formulareinsendungen oder Events zu erstellen oder zu aktualisieren.

Diese Prozesse überprüfen nicht die E-Mail-Adresse selbst auf Gültigkeit (wie es z. B. ein eingebettetes Formular würde), sondern deren Format. Zusätzlich zu deren Gültigkeit gemäß RFC 2822 erlegen wir die folgenden Beschränkungen auf E-Mail-Adressen:

  • Es ist nicht zulässig, die lokalen Teile in Anführungszeichen zu setzen. (z. B. ist "Test-E-Mail"@hubspot.com nicht gültig)
  • Der Domain-Teil muss in einer gültigen TLD enden, die unter https://data.iana.org/TLD/tlds-alpha-by-domain.txt aufgeführt ist (Bitte beachten Sie, dass sich dies auf nach dem Handling von Unicode-TDLs bezieht. "user@email.삼성" ist also eine gültige E-Mail-Adresse).
  • Wenn Sie die v3-Formulare-API verwenden, kann die Validierung ignoriert werden, indem Sie den skipValidation-Parameter zum Anfragetext hinzufügen und diesen auf true festlegen.

Wie lege ich mehrere Werte für Kontrollkästcheneigenschaften fest?

Wenn Sie mehrere Werte für eine Kontrollkästchen-Eigenschaft festlegen, sollten die Werte mit einem Semikolon (;) getrennt werden.
Beispiel: 'value1;value2;value5'

Beim Aktualisieren eines Datensatzes über die CRM-Objektendpunkte sollte der Eigenschaftswert eine einzige Zeichenfolge sein, bei der alle Werte durch Semikolons getrennt sind:

{
  "properties":
    {
      "example_property": "value1;value3;value4"
    }
}

Stellen Sie für die Formulare-Endpunkte sicher, dass die Semikolons auch URL-codiert sind:

...&example_property=value1%3Bvalue2%3Bvalue4


Gibt es Limits für Kontaktdatensätze?

HubSpot verfügt über einige Limits in Bezug auf zusammengeführte Kontaktdatensätze und Formulareinsendungen für Kontaktdatensätze:

  1. Es gibt ein Limit von 250 verlinkten Identitäten pro Kontakt.
    • Wenn Sie versuchen, zwei Kontakte zusammenzuführen, und der resultierende Kontakt hat mehr als 250 Identitäten, erhalten Sie einen Fehler.
  2. Kontakte sind auf 1.000 Formulareinsendungen beschränkt. Einsendungen, bei denen ein Kontakt dieses Limit dann überschreiten würde, werden sofort verworfen:
    • Die Formulardaten aktualisieren den Kontaktdatensatz nicht.
    • Die Einsendung selbst wird für den Kontaktdatensatz nicht angezeigt, weder in den form-submissions-Daten von den Kontakte-Endpunkten noch in der Chronik des Kontakts.
    • Die Einsendung wird nicht auf Listenmitgliedschaften oder Workflows geprüft.
    • Die Einsendung wird nicht in der Einsendungsliste für das Anzeigen des Formulars in HubSpot angezeigt.

Wenn Sie eines dieser Limits aufgrund eines Tests überschreiten, empfehlen wir, die Testkontakte zu löschen und einen neuen Testdatensatz zu erstellen. Durch Verwendung der gleichen E-Mail-Adresse im neuen Kontaktdatensatz wird der gelöschte Kontakt nicht wiederhergestellt, und alle Formulareinsendungen mit der E-Mail werden dem neuen Datensatz zugeordnet.


Wie kann ich Transaktions-E-Mails versenden?

HubSpot unterstützt zwei Methoden zum Senden von transaktionsbezogenen E-Mails: Die SMTP-API und die Single-Send-API.

Verwendung der SMTP-API

Die SMTP-API versendet nicht direkt E-Mails. Sie wird nur verwendet, um Anmeldedaten für den HubSpot SMTP-Server abzurufen. Nachdem Sie ein Token und ein Passwort mithilfe der  SMTP-API erhalten haben, müssen Sie diese Anmeldeinformationen verwenden, um sich beim SMTP-Server von HubSpot anzumelden und die E-Mail über SMTP zu senden. Die Anmeldedetails (Hostname und Port) für den SMTP-Server finden Sie auf der  Seite der Dokumentation. Die E-Mail und Links werden umgebrochen, um das HubSpot-E-Mail-Tracking zu unterstützen; andernfalls müssen Sie den gesamten E-Mail-Inhalt erstellen.

Verwendung der Single-Send-API

Die Single-Send-API verwendet im HubSpot-E-Mail-Tool erstellte Vorlagen-E-Mails zusammen mit einer JSON-formatierten POST-API, um E-Mails zu senden. Zunächst müssen Sie eine E-Mail in HubSpot erstellen und „Für Single-Send-API speichern“ auswählen, wenn Sie den Empfänger auswählen.  Nachdem die E-Mail erstellt wurde, können Sie die API verwenden, um die E-Mail an einen Kontakt zu senden. Dabei werden die Details für den Empfänger (einschließlich aller Kontakt- oder benutzerdefinierten Eigenschaften, die in der E-Mail eingerichtet wurden) im Text der API-Anfrage festgelegt.  Weitere Details zum Format dieser JSON-Anfrage finden Sie auf der  Seite der Dokumentation.


Wie kann ich die API-Updates abonnieren?

Updates für HubSpot-APIs und Entwickler-Tools werden über unser Entwickler-Änderungsprotokoll vorgenommen.

Sie können das Formular auf der linken Seite verwenden, um Updates zu abonnieren. Wählen Sie die Option „Sofort“ für die Häufigkeit, um Benachrichtigungen zu erhalten, sobald sie bekannt sind. Andernfalls wählen Sie eine der anderen Häufigkeiten aus, um eine Zusammenfassung der Updates in dem Intervall Ihrer Wahl zu erhalten.


Wie gewährleiste ich den Datenschutz und die Einhaltung rechtlicher Vorgaben beim Arbeiten mit der HubSpot-Plattform?

Überwachen der Rechtmäßigkeit der Verarbeitung von Daten in HubSpot

Laut DSGVO benötigen Unternehmen einen rechtmäßigen Grund zur Verwendung und Verarbeitung von personenbezogenen Daten, müssen die Einwilligung zur Erfassung und Verarbeitung personenbezogener Daten seitens ihrer Nutzer dokumentieren und die Verarbeitung zu anderen rechtmäßigen Zwecken beweisen können.

Die Kontakteigenschaft Rechtliche Grundlage für die Verarbeitung der Kontaktdaten ermöglicht es Ihnen, die Rechtmäßigkeit der Verarbeitung von Kontaktdaten in Ihrem HubSpot-Account per Vertrag, berechtigtem Interesse und/oder Einwilligung zu erfassen, nachzuverfolgen und zu speichern.

Wenn Sie Kontaktdaten über die Kontakte-Endpunkte aufrufen, verwendet diese Eigenschaft den Namen hs_legal_basis. Wie bei jeder anderen Kontakteigenschaft würde jeder Kontakt mit dieser Eigenschaft über die API aufrufbar sein. Die Eigenschaft kann auch über die API für Kontaktdatensätze festgelegt oder aktualisiert werden.

Die Eigenschaftsoptionen können jedoch nicht durch die API geändert werden. Sie können nur innerhalb von HubSpot aktualisiert werden. Es ist jedoch möglich, benutzerdefinierte Optionen, die möglicherweise über die Kontakteigenschaftenendpunkte für die Eigenschaft festgelegt wurden, zu übernehmen. Da einzelne HubSpot-Accounts möglicherweise nicht die Standardeinstellungen verwenden, wird empfohlen, diese Endpunkte zum Abrufen der Eigenschaftsoptionen zu verwenden.

Weitere Informationen zu dieser Eigenschaft und wie sie in HubSpot verwendet werden kann, finden Sie in diesem
Wissensdatenbank-Artikel.

Handhaben von datenschutzkonformen Kontaktlöschungen

HubSpot-Benutzer haben die Möglichkeit, einen Kontaktdatensatz dauerhaft zu löschen, um Datenschutzgesetze einzuhalten. Weitere Informationen finden Sie in diesem Artikel in der Wissensdatenbank.

Sie können den Abonnementtyp contact.privacyDeletion abonnieren, um Webhook-Benachrichtigungen zu erhalten, wenn ein Benutzer eine datenschutzkonforme Kontaktlöschung durchführt. Weitere Informationen zu Webhooks-Übersicht und die Handhabung dieser Benachrichtigungen finden Sie in der Übersicht über Webhooks.