Benutzerdefinierte Objekte

APPLICABLE PRODUCTS
  • 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.

Authentifizierungsmethoden

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.

Ein benutzerdefiniertes Objekt erstellen

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. 

Eigenschaften

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.
    custom-object-secondary-display-properties0
    • 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
        custom-object-dashboard-filter0
    • Um eine Anzeigeeigenschaft von der Benutzeroberfläche zu entfernen, müssen Sie die Eigenschaft zunächst löschen und dann neu erstellen.

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.

Zulässige Werte für type
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
Zulässige Werte für fieldType 
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:

// Example associatedObjects array "associatedObjects": [ "CONTACT", "COMPANY", "TICKET", "DEAL", "2-3453932" ]

Vorhandene benutzerdefinierte Objekte abrufen

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 den

    fullyQualifiedName eines Objekts in seinem Schema finden, das von p{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

Vorhandene benutzerdefinierte Objekte aktualisieren

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 und secondaryDisplayProperties 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:

// Example association request body { "fromObjectTypeId": "2-3444025", "toObjectTypeId": "ticket", "name": "cat_to_ticket" }

Ein benutzerdefiniertes Objekt löschen

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.

Beispiel für benutzerdefiniertes Objekt

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:

  1. Das Erstellen eines benutzerdefinierten Objektschemas.
  2. Das Erstellen eines benutzerdefinierten Objektdatensatzes.
  3. Das Zuordnen eines benutzerdefinierten Objektdatensatzes zu einem HubSpot-Kontakt.
  4. Das Erstellen einer neuen Zuordnungsdefinition zwischen dem benutzerdefinierten Objekt und dem HubSpot-Ticket.
  5. Das Erstellen einer neuen Eigenschaftsdefinition.
  6. 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: 

  1. Zustand (neu oder gebraucht): Enumeration
  2. Datum des Eingangs beim Händler: Datum
  3. Jahr: Zahl
  4. Automarke: Zeichenfolge
  5. Modell: Zeichenfolge
  6. VIN: Zeichenfolge (eindeutiger Wert)
  7. Farbe: Zeichenfolge
  8. Kilometerstand: Zahl
  9. Preis: Zahl
  10. 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

// Example POST request to https://api.hubspot.com/crm/v3/schemas { "name": "cars", "labels": { "singular": "Car", "plural": "Cars" }, "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "make" ], "searchableProperties": [ "year", "make", "vin", "model" ], "requiredProperties": [ "year", "make", "vin", "model" ], "properties": [ { "name": "condition", "label": "Condition", "type": "enumeration", "fieldType": "select", "options": [ { "label": "New", "value": "new" }, { "label": "Used", "value": "used" } ] }, { "name": "date_received", "label": "Date received", "type": "date", "fieldType": "date" }, { "name": "year", "label": "Year", "type": "number", "fieldType": "number" }, { "name": "make", "label": "Make", "type": "string", "fieldType": "text" }, { "name": "model", "label": "Model", "type": "string", "fieldType": "text" }, { "name": "vin", "label": "VIN", "type": "string", "hasUniqueValue": true, "fieldType": "text" }, { "name": "color", "label": "Color", "type": "string", "fieldType": "text" }, { "name": "mileage", "label": "Mileage", "type": "number", "fieldType": "number" }, { "name": "price", "label": "Price", "type": "number", "fieldType": "number" }, { "name": "notes", "label": "Notes", "type": "string", "fieldType": "text" } ], "associatedObjects": [ "CONTACT" ] }

Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren

// Example response body HTTP 201 { "name": "cars" "labels": { "singular": "Car", "plural": "Cars" }, "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "make" ], "searchableProperties": [ "year", "make", "vin", "model" ], "requiredProperties": [ "year", "make", "vin", "model" ], "archived": false, "restorable": true, "metaType": "PORTAL_SPECIFIC", "id": "3465404", "fullyQualifiedName": "p1234567_cars", "createdAt": "2021-10-01T15:15:07.340Z", "updatedAt": "2021-10-01T15:15:07.340Z", "objectTypeId": "2-3465404", "properties": [ { { "id": "529881", "createdAt": "2020-02-23T01:24:54.508774Z", "updatedAt": "2020-02-23T01:24:54.508774Z", "properties": [ { "updatedAt": "2020-02-23T01:24:54.665Z", "createdAt": "2020-02-23T01:24:54.665Z", "name": "condition", "label": "Condition", "type": "enumeration", "fieldType": "select", "groupName": "car_information", "options": [ { "label": "New", "value": "new", "displayOrder": -1, "hidden": false }, { "label": "Used", "value": "used", "displayOrder": -1, "hidden": false } ], "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.667Z", "createdAt": "2020-02-23T01:24:54.667Z", "name": "date_received", "label": "Date received", "type": "date", "fieldType": "date", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.667Z", "createdAt": "2020-02-23T01:24:54.667Z", "name": "year", "label": "Year", "type": "number", "fieldType": "number", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.670Z", "createdAt": "2020-02-23T01:24:54.670Z", "name": "model", "label": "Model", "type": "string", "fieldType": "text", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.670Z", "createdAt": "2020-02-23T01:24:54.670Z", "name": "vin", "label": "VIN", "type": "string", "fieldType": "text", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": true, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.670Z", "createdAt": "2020-02-23T01:24:54.670Z", "name": "notes", "label": "Notes", "type": "string", "fieldType": "text", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.670Z", "createdAt": "2020-02-23T01:24:54.670Z", "name": "color", "label": "Color", "type": "string", "fieldType": "text", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.667Z", "createdAt": "2020-02-23T01:24:54.667Z", "name": "mileage", "label": "Mileage", "type": "number", "fieldType": "number", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.667Z", "createdAt": "2020-02-23T01:24:54.667Z", "name": "price", "label": "Price", "type": "number", "fieldType": "number", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }, { "updatedAt": "2020-02-23T01:24:54.667Z", "createdAt": "2020-02-23T01:24:54.667Z", "name": "make", "label": "Make", "type": "string", "fieldType": "text", "groupName": "car_information", "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false } ], "associations": [ { "id": "1", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "2-529881", "toObjectTypeId": "0-1", "name": "car_to_contact" }, { "id": "2", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "0-1", "toObjectTypeId": "2-529881", "name": "car_to_contact" }, { "id": "13", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "2-529881", "toObjectTypeId": "0-27", "name": "car_to_task" }, { "id": "14", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "0-27", "toObjectTypeId": "2-529881", "name": "car_to_task" }, { "id": "15", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "2-529881", "toObjectTypeId": "0-46", "name": "car_to_note" }, { "id": "16", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "0-46", "toObjectTypeId": "2-529881", "name": "car_to_note" }, { "id": "7", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "2-529881", "toObjectTypeId": "0-48", "name": "car_to_call" }, { "id": "8", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "0-48", "toObjectTypeId": "2-529881", "name": "car_to_call" }, { "id": "11", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "2-529881", "toObjectTypeId": "0-51", "name": "car_to_conversation_session" }, { "id": "12", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "0-51", "toObjectTypeId": "2-529881", "name": "car_to_conversation_session" }, { "id": "9", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "2-529881", "toObjectTypeId": "0-49", "name": "car_to_email" }, { "id": "10", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "0-49", "toObjectTypeId": "2-529881", "name": "car_to_email" }, { "id": "5", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "2-529881", "toObjectTypeId": "0-47", "name": "car_to_meeting_event" }, { "id": "6", "createdAt": null, "updatedAt": null, "fromObjectTypeId": "0-47", "toObjectTypeId": "2-529881", "name": "car_to_meeting_event" } ] }

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:

// Example POST request to https://api.hubspot.com/crm/v3/objects/2-3465404 { "properties": { "condition": "used", "date_received": "1582416000000", "year": "2014", "make": "Nissan", "model": "Frontier", "vin": "4Y1SL65848Z411439", "color": "White", "mileage": "80000", "price": "12000", "notes": "Excellent condition. No accidents." } }

Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren

// Example response body { "id": "181308", "properties": { "color": "White", "condition": "used", "make": "Nissan", "mileage": "80000", "model": "Frontier", "vin": "4Y1SL65848Z411439", "notes": "Excellent condition. No accidents.", "price": "12000", "year": "2014", "date_received": "1582416000000" }, "createdAt": "2020-02-23T01:44:11.035Z", "updatedAt": "2020-02-23T01:44:11.035Z", "archived": false }

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:

// Example POST request to https://api.hubspot.com/crm/v3/schemas/2-3465494/associations { "fromObjectTypeId": "2-3465404", "toObjectTypeId": "ticket", "name": "car_to_ticket" }

Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren

// Example response { "id": "121", "createdAt": "2020-02-23T01:52:12.893826Z", "updatedAt": "2020-02-23T01:52:12.893826Z", "fromObjectTypeId": "2-3465404", "toObjectTypeId": "0-5", "name": "car_to_ticket" }

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:

// Example POST request to https://api.hubspot.com/crm/v3/properties/2-3465404 { "groupName": "car_information", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "options": [ { "label": "Basic", "value": "basic" }, { "label": "Oil change only", "value": "oil_change_only" }, { "label": "Scheduled", "value": "scheduled" } ] }

Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren

// Example response { "updatedAt": "2020-02-23T02:08:20.055Z", "createdAt": "2020-02-23T02:08:20.055Z", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "groupName": "car_information", "options": [ { "label": "Basic", "value": "basic", "displayOrder": -1, "hidden": false }, { "label": "Oil change only", "value": "oil_change_only", "displayOrder": -1, "hidden": false }, { "label": "Scheduled", "value": "scheduled", "displayOrder": -1, "hidden": false } ], "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }

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: 

// Example PATCH request to https://api.hubspot.com/crm/v3/schemas/2-3465404 { "secondaryDisplayProperties": [ "maintenance_package" ] }

Die Antwort für diesen API-Aufruf sieht ungefähr so aus:Alles kopieren

// Example response { "id": "3465404", "createdAt": "2020-02-23T01:24:54.537Z", "updatedAt": "2020-02-23T02:12:24.175874Z", "labels": { "singular": "Car", "plural": "Cars" }, "requiredProperties": [ "year", "model", "vin", "make" ], "searchableProperties": [ "year", "model", "vin", "make" ], "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "maintenance_package" ], "portalId": 1234567, "name": "car" }

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:

Screen Shot 2020-03-06 at 11.08.41 AM

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.


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.