Benutzerdefinierte Objekte
Marketing Hub
- Enterprise
Sales Hub
- Enterprise
Service Hub
- Enterprise
CMS Hub
- Enterprise
Operations Hub
- Enterprise
In each HubSpot account, there are the standard CRM objects: contacts, companies, deals, and tickets. To represent and organize your CRM data based on your business needs, you can also create custom objects. You can create a custom object in HubSpot, or use the custom objects API to define custom objects, properties, and associations to other CRM objects.
Below, learn how to create and manage custom objects through the API, and see a walkthrough of creating an example custom object.
To learn more about creating custom objects, check out the following posts on the HubSpot developer blog:
Please note: custom objects are specific to each account, and depending on your subscription, there are limits on the number of custom objects you can create. Learn more about your limits in the HubSpot Products & Services catalog.
Sie können benutzerdefinierte Objekte mithilfe einer der folgenden Authentifizierungsmethoden erstellen, lesen und aktualisieren:
Please note: as of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. During this deprecation phase, HubSpot may deactivate your key at any time.
You should instead authenticate using a private app access token or OAuth. Learn more about this change and how to migrate an API key integration to use a private app instead.
Um ein benutzerdefiniertes Objekt zu erstellen, müssen Sie zunächst das Objektschema definieren. Das Schema enthält den Objektnamen, Eigenschaften und Zuordnungen zu anderen CRM-Objekten. Die vollständigen Schema-Anfragedetails finden Sie oben in diesem Artikel auf der Registerkarte „Objektschema“. Sie können sich auch eine Beispielanfrage in der Beispieldemonstration unten ansehen.
Um das benutzerdefinierte Objektschema zu erstellen, führen Sie eine
POST
-Anfrage an crm/v3/schemas
durch. Fügen Sie im Anfragetext Definitionen für Ihr Objektschema ein, einschließlich Name, Eigenschaften und Zuordnungen.
Wenn Sie Ihr benutzerdefiniertes Objekt benennen, beachten Sie Folgendes:
- Sobald Sie ein Objekt erstellt haben, können der Name und das Label des Objekts nicht mehr geändert werden.
- Der Name darf nur Buchstaben, Ziffern, Unterstriche und Bindestriche enthalten.
- Das erste Zeichen des Namens muss ein Buchstabe sein.
- Lange Label können in bestimmten Teilen des Produkts abgeschnitten werden.
Im Folgenden finden Sie die erforderlichen Definitionen für die Eigenschaften und Zuordnungen des Objekts.
Die Eigenschaften, die Sie im Anfragetext definieren, werden verwendet, um Informationen zu einzelnen benutzerdefinierten Objektdatensätzen zu speichern.
Please note: you can have up to 10 unique value properties for each custom object in your HubSpot account.
Sie verwenden Ihre definierten Eigenschaften, um die folgenden eigenschaftsbasierten Felder zu füllen:
- requiredProperties: Die Eigenschaften, die beim Erstellen eines neuen benutzerdefinierten Objektdatensatzes erforderlich sind.
- searchableProperties: Die Eigenschaften, die für die Suche in HubSpot indiziert werden.
- primaryDisplayProperty: Die Eigenschaft, die zum Benennen einzelner benutzerdefinierter Objektdatensätze verwendet wird.
- secondaryDisplayProperties: Die Eigenschaften, die in einzelnen Datensätzen unter der primären Anzeigeeigenschaft angezeigt werden.
- Die erste Eigenschaft, die in
secondaryDisplayProperties
aufgeführt ist, wird auch als vierter Filter auf der Indexseite des Objekts hinzugefügt, wenn es sich um einen der folgenden Eigenschaftstypen handelt:string
number
enumeration
boolean
datetime
- Um eine Anzeigeeigenschaft von der Benutzeroberfläche zu entfernen, müssen Sie die Eigenschaft zunächst löschen und dann neu erstellen.
- Die erste Eigenschaft, die in
Beim Erstellen von Eigenschaften über die Schemaanfrage
wird standardmäßig der type
der Eigenschaft auf string
und der fieldType
auf text
festgelegt. Unten sind die Werte, die Sie verwenden können, um verschiedene Typen von Eigenschaften zu erstellen.
type |
Beschreibung | Zulässige fieldType -Werte |
---|---|---|
enumeration |
Eine Zeichenfolge, die eine Reihe von Optionen enthält, die durch ein Semikolon getrennt sind | booleancheckbox , checkbox , radio , select |
date |
Ein ISO 8601-formatierter Wert, der einen bestimmten Tag, einen bestimmten Monat und ein bestimmtes Jahr darstellt. | date |
dateTime |
Ein ISO 8601-formatierter Wert, der einen bestimmten Tag, einen bestimmten Monat, ein bestimmtes Jahr und eine bestimmte Uhrzeit darstellt. Die HubSpot-App zeigt nicht die Uhrzeit an. | date |
string |
Eine Klartext-Zeichenfolge, die auf 65.536 Zeichen begrenzt ist. | file , text , textarea |
number |
Ein Zahlenwert mit numerischen Ziffern und höchstens einer Dezimalstelle. | number |
fieldType |
Beschreibung |
---|---|
booleancheckbox |
Eine Eingabe, die es Benutzern ermöglicht, entweder „Ja“ oder „Nein“ auszuwählen. Bei Verwendung in einem Formular wird sie als einzelnes Kontrollkästchen angezeigt. |
checkbox |
Eine Liste der Kontrollkästchen, anhand derer ein Benutzer mehrere Optionen aus einer Reihe von Optionen auswählen kann, die für die Eigenschaft zulässig sind. |
date |
Ein Datumswert, der als Datumsauswahl angezeigt wird. |
file |
Ermöglicht, dass eine Datei zu einem Formular hochgeladen wird. Wird als URL-Link gespeichert und der Datei angezeigt. |
number |
Eine Ziffernfolge oder Zahlen in Dezimalschreibweise oder in wissenschaftlicher Notation. |
radio |
Eine Eingabe, die es Benutzern ermöglicht, eine Option aus einer Reihe von Optionen auszuwählen, die für die Eigenschaft zulässig sind. Bei Verwendung in einem Formular wird dies als eine Reihe von Optionsfeldern angezeigt. |
select |
Eine Dropdown-Eingabe, die es Benutzern ermöglicht, eine Option aus einer Reihe von Optionen auszuwählen, die für die Eigenschaft zulässig sind. |
text |
Eine Klartext-Zeichenfolge, die als eine einzeilige Texteingabe angezeigt wird. |
textarea |
Eine Klartext-Zeichenfolge, die als eine mehrzeilige Texteingabe angezeigt wird. |
Zuordnungen
HubSpot ordnet den E-Mails, Meetings, Notizen, Aufgaben, Anrufen und Konversationen automatisch ein benutzerdefiniertes Objekt zu. Sie können außerdem Ihr benutzerdefiniertes Objekt auch mit anderen Standard-HubSpot-Objekten oder anderen benutzerdefinierten Objekten verknüpfen.
Identifizieren Sie beim Erstellen von Zuordnungen über die Anfrage zum Erstellen eines Schemas Standardobjekte anhand ihres Namens und benutzerdefinierte Objekte anhand ihres objectTypeId
-Werts. Zum Beispiel:
Um alle benutzerdefinierten Objekte abzurufen, führen Sie eine GET
-Anfrage an /crm/v3/schemas
durch.
Um ein bestimmtes benutzerdefiniertes Objekt abzurufen, führen Sie eine GET
-Anfrage an einen der folgenden Endpunkte durch:
/crm/v3/schemas/{objectTypeId}
/crm/v3/schemas/p_{object_name}
/crm/v3/schemas/{fullyQualifiedName}
. Sie können denfullyQualifiedName
eines Objekts in seinem Schema finden, das vonp{portal_id}_{object_name}
abgeleitet wird. Sie können die Portal-ID Ihres Accounts mithilfe der Account-Informationen-API finden.
Für einen Account mit der ID 1234
und ein Objekt mit dem Namen lender
könnte Ihre Anfrage-URL beispielsweise wie folgt aussehen:
https://api.hubapi.com/crm/v3/schemas/2-3465404
https://api.hubapi.com/crm/v3/schemas/p_lender
https://api.hubapi.com/crm/v3/schemas/p1234_lender
Um das Schema eines Objekts zu aktualisieren, führen Sie eine PATCH
-Anfrage an https://api.hubapi.com/crm/v3/schemas/{objectTypeId}
durch.
Sobald Ihr benutzerdefiniertes Objekt definiert ist:
- Der Name und das Label des Objekts (Singular und Plural) können nicht geändert werden.
- Die
requiredProperties
,searchableProperties
,primaryDisplayProperty
undsecondaryDisplayProperties
können durch Aktualisieren des Schemas des Objekts geändert werden. Um eine neue Eigenschaft als erforderlich, durchsuchbar oder Anzeigeeigenschaft festzulegen, müssen Sie die Eigenschaft vor dem Aktualisieren des Schemas erstellen. - Sie können benutzerdefinierte Objekteigenschaften entweder in HubSpot oder über die Eigenschaften-API erstellen und bearbeiten.
Zuordnungen aktualisieren
Um weitere Objektzuordnungen zu Ihrem benutzerdefinierten Objekt hinzuzufügen, führen Sie eine
POST
-Anfrage an/crm/v3/schemas/{objectTypeId}/associations
durch.
Sie können Ihr benutzerdefiniertes Objekt nur Standard-HubSpot-Objekten (z. B. Kontakte, Unternehmen, Deals oder Tickets) oder anderen benutzerdefinierten Objekten zuordnen. Identifizieren Sie im toObjectTypeId
-Feld benutzerdefinierte Objekte nach ihrem objectTypeId
-Wert und Standardobjekte nach ihrem Namen. Beispiel:
Sie können ein benutzerdefiniertes Objekt nur löschen, nachdem alle Objektinstanzen von diesem Typ gelöscht wurden. Um ein benutzerdefiniertes Objekt zu löschen, führen Sie eine DELETE
-Anfrage an /crm/v3/schemas/{objectType}
durch.
Wenn Sie ein neues benutzerdefiniertes Objekt mit dem gleichen Namen wie das gelöschte Objekt erstellen müssen, müssen Sie das Schema dauerhaft löschen, indem Sie eine DELETE
-Anfrage an /crm/v3/schemas/{objectType}?archived=true
durchführen. Sie können einen benutzerdefinierten Objekttyp nur löschen, nachdem alle Objektinstanzen von diesem Typ, alle Zuordnungen und benutzerdefinierten Objekteigenschaften gelöscht wurden.
Im Folgenden finden Sie eine Demonstration zum Erstellen eines benutzerdefinierten Beispielobjekts. Die vollständigen Informationen der angezeigten Anfragen finden Sie auf der Registerkarte „Objektdefinition“ oben im Artikel.
In dieser Demonstration wird Folgendes behandelt:
- Das Erstellen eines benutzerdefinierten Objektschemas.
- Das Erstellen eines benutzerdefinierten Objektdatensatzes.
- Das Zuordnen eines benutzerdefinierten Objektdatensatzes zu einem HubSpot-Kontakt.
- Das Erstellen einer neuen Zuordnungsdefinition zwischen dem benutzerdefinierten Objekt und dem HubSpot-Ticket.
- Das Erstellen einer neuen Eigenschaftsdefinition.
- Das Aktualisieren des Objektschemas (d. h.
secondaryDisplayProperties
) mit der neuen Eigenschaft.
Ziel: Ein Autohaus namens CarSpot möchte seinen Bestand mithilfe eines benutzerdefinierten Objekts in HubSpot speichern. Um die Fahrzeughaltung und die Käufe von Fahrzeugen nachzuverfolgen, ordnet CarSpot Autos Kontaktdatensätzen zu. In Rahmen dieses Plans verfolgt CarSpot auch die Fahrzeugwartung mithilfe von HubSpot-Tickets und benutzerdefinierten Eigenschaften nach.
Erstellen des Objektschemas
CarSpot muss ein Objektschema erstellen, das die folgenden Attribute als Eigenschaften darstellen kann:
- Zustand (neu oder gebraucht): Enumeration
- Datum des Eingangs beim Händler: Datum
- Jahr: Zahl
- Automarke: Zeichenfolge
- Modell: Zeichenfolge
- VIN: Zeichenfolge (eindeutiger Wert)
- Farbe: Zeichenfolge
- Kilometerstand: Zahl
- Preis: Zahl
- Anmerkungen: Zeichenfolge
Das Autohaus definiert außerdem eine Verknüpfung zwischen seinem benutzerdefinierten Objekt und dem Standard-Kontaktobjekt, damit es Autos mit potenziellen Käufern verknüpfen kann.
Nach das Datenmodell von CarSpot abgeschlossen ist, erstellt es das Objektschema, indem es eine POST
-Anfrage an /crm/v3/schemas
mit dem folgenden Anfragetext durchführt:alles
Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren
After creating the object schema, CarSpot makes sure to note the new object's {objectTypeId}
field, as they'll use this for fetching and updating the object later. They can also use the {fullyQualifiedName}
value, if they prefer.
Erstellen eines benutzerdefinierten Objektdatensatzes
Mit dem erstellten benutzerdefinierten Objekt kann CarSpot jetzt Datensätze im Objekt für jedes Auto in seinem Bestand erstellen.
Es erstellt sein erstes Auto, indem es eine POST
-Anfrage an /crm/v3/objects/2-3465404
mit dem folgenden Anfragetext durchführt:
Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren
Da der Datensatz erstellt ist, kann CarSpot den id
-Wert verwenden, um das Auto später einem vorhandenen Kontakt zuzuordnen.
If they wanted to later retrieve this record along with specific properties, they could make a GET
request to https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=model
Zuordnen des benutzerdefinierten Objektdatensatzes zu einem anderen Datensatz
Mit der ID des neuen Fahrzeugdatensatzes (181308
) und der ID eines anderen Datensatzes können Sie einen benutzerdefinierten Objektdatensatz einem Datensatz eines anderen Objekts zuordnen.
Um eine Zuordnung zu erstellen, führen Sie eine PUT
-Anfrage an /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}
durch. Wenn die Objektbeziehung bereits definiert ist, führen Sie eine GET
-Anfrage an crm/v3/schemas/{objectType}
durch, um den associationType
-Wert zu bestimmen.
Beispielsweise kann CarSpot mit der Kontakt-ID 51
und dem Zuordnungstyp 75
den Fahrzeugdatensatz einem Kontakt zuordnen. Mithilfe der obigen IDs wird die Anfrage-URL wie folgt erstellt:
https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75
Definieren einer neuen Zuordnung
CarSpot möchte nun damit beginnen, die nach dem Verkauf geleisteten Dienstleistungen für seine Autos nachzuverfolgen. Dazu verwendet es HubSpot-Tickets, um alle durchgeführten Wartungsarbeiten zu protokollieren.
Um Verknüpfungen zwischen Autos und Tickets zu ermöglichen, erstellt es eine neue Zuordnung, indem es eine POST
-Anfrage
an /crm/v3/schemas/2-3465404/associations
mit dem folgenden Anfragetext durchführt:
Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren
When creating a new association between two custom objects, specify the custom objects by their objectTypeId in the toObjectTypeId field. For standard objects, you can identify them by name or use the following values:
- Contact: 0-1
- Company: 0-2
- Deal: 0-3
- Ticket: 0-5
Definieren einer neuen Eigenschaft
Beim Nachverfolgen der Wartung erkennt CarSpot eine Möglichkeit, Wartungsdienste in Paketen zu bündeln. Um diese Wartungspakete in einzelnen Fahrzeugdatensätzen nachzuverfolgen, erstellt das Autohaus eine neue Enumerationseigenschaft, die die verfügbaren Pakete enthält.
Um eine neue Eigenschaft zu definieren, führt es eine POST
-Anfrage
an /crm/v3/properties/2-3465404
mit dem folgenden Anfragetext durch:
Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren
Da jetzt die Eigenschaft erstellt ist, möchtet das Autohaus, dass sie in der Seitenleiste der einzelnen Fahrzeugdatensätze angezeigt wird, sodass die Informationen problemlos seinen Vertriebsmitarbeitern und Technikern zur Verfügung stehen. Dazu fügt CarSpot die Eigenschaft zu secondaryDisplayProperties
hinzu, indem es eine PATCH
-Anfrage an /crm/v3/schemas/2-3465404
mit dem folgenden Anfragetext durchführt:
Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren
Wenn nun ein Techniker einen Kontaktdatensatz öffnet, dem ein Fahrzeug zugeordnet ist, wird die Eigenschaft auf der Karte für benutzerdefinierte Objekte in der Seitenleiste angezeigt:
Da CarSpot weiterhin HubSpot nutzt, findet es wahrscheinlich noch mehr Möglichkeiten, dieses benutzerdefinierte Objekt mithilfe der HubSpot-API zu verfeinern und zu erweitern. Es könnte sich sogar dazu entschließen, dynamische Seiten mithilfe seiner benutzerdefinierten Objektdaten zu erstellen.
Vielen Dank, dass Sie Ihr Feedback mit uns geteilt haben.