Hubspot

Diese Anleitung zeigt, wie du dich über die HubSpot API authentifizierst und grundlegende API-Abfragen wie das Erstellen von Kontakten, das Abrufen von Kontaktdaten oder das Erstellen von Tickets durchführst. Die Integration eignet sich z. B. zur Verbindung eines Chatbots mit HubSpot, um Kundendaten oder Support-Tickets automatisch zu verwalten.

---

🔐 1. Authentication & Authorization

✅ Voraussetzungen

Um API-Abfragen durchführen zu können, musst du ein verifizierter Benutzer in HubSpot sein. Es gibt zwei Möglichkeiten zur Authentifizierung:

• OAuth 2.0: Wird verwendet, wenn mehrere Benutzerzugriffe oder Autorisierung per Login erforderlich ist

• Private Apps (Access Token): Einfachste Methode für serverseitige Integrationen, ideal für Systeme wie melibo

---

🧩 Private Apps – Access Token erstellen

1. Melde dich in deinem HubSpot-Konto an.

2. Navigiere zu Einstellungen → Account Setup → Integration → Private Apps.

3. Klicke auf „Create a private app“.

4. Fülle die Tabs Basic Info und Scopes aus.

5. Nach der Erstellung:

   • Lässt sich der Access Token anzeigen und kopieren.

   • Speichere den Token sicher – er wird nur einmal angezeigt.

Dieser Access Token ist alles, was z. B. melibo benötigt, um eine Integration mit HubSpot herzustellen.

---

🔧 Verwendung des Access Tokens

Der Access Token kann in den Authorization-Header integriert werden.

Beispiel:

Header-Option 1 – Bearer Token

Authorization: Bearer <ACCESS_TOKEN>

Header-Option 2 – Key/Value Header

Key: Authorization
Value: Bearer <ACCESS_TOKEN>

Beispiel-Endpunkt:

GET https://api.hubapi.com/contacts/v1/lists/all/contacts/all

Bewahre den Token sicher auf! Er gewährt Zugriff auf deine HubSpot-Daten und sollte niemals öffentlich geteilt werden.

---

🧾 Berechtigungen (Scopes)

Für die Ticket-Automation werden u. a. folgende Berechtigungen benötigt:

• crm.objects.contacts.read/write

• crm.objects.tickets.read/write

• crm.schemas.contacts.read

• crm.schemas.tickets.read

Prüfe in den Einstellungen deiner Private App, ob diese Berechtigungen aktiv sind, um Fehler bei der Integration zu vermeiden.

---

🧠 2. Use Cases – Beispiele für API-Abfragen

📇 Beispiel 1: Create a Contact

Diese Abfrage erstellt einen neuen Kontakt in HubSpot – nützlich, wenn dein Chatbot neue Kundendaten erfassen soll.

Type: POST URL: https://api.hubspot.com/crm/v3/objects/contacts Header:

Content-Type: application/json
Authorization: Bearer {token}

Body (Beispiel):

{
  "properties": {
    "email": "[email protected]",
    "firstname": "Jane",
    "lastname": "Doe"
  }
}

Response (Beispiel):

{
  "id": "123456",
  "properties": {
    "createdate": "2024-06-04T10:15:20.000Z",
    "email": "[email protected]",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "123-456-7890",
    "company": "Example Company",
    "hubspot_owner_id": "13579",
    "hs_object_id": "123456"
  },
  "createdAt": "2024-06-04T10:15:20.000Z",
  "updatedAt": "2024-06-04T10:15:20.000Z",
  "archived": false
}

---

🔍 Beispiel 2: Get a Contact by Email

Diese Abfrage ruft die Daten eines spezifischen Kontakts anhand seiner E-Mail-Adresse ab.

Type: GET URL:

https://api.hubapi.com/contacts/v1/contact/email/{contact_email}/profile

Header:

Content-Type: application/json
Authorization: Bearer {token}

Response (Beispiel):

{
  "vid": 123456,
  "portal-id": 67890,
  "is-contact": true,
  "properties": {
    "firstname": { "value": "John" },
    "lastname": { "value": "Doe" },
    "email": { "value": "[email protected]" },
    "phone": { "value": "123-456-7890" },
    "company": { "value": "Example Company" },
    "lifecyclestage": { "value": "customer" }
  }
}

💡 Diese Abfrage eignet sich perfekt, um bestehende Kontakte im Chat oder Support-Prozess automatisch zu identifizieren.

---

🎫 Beispiel 3: Create a Ticket

Diese Abfrage erstellt ein neues Ticket in HubSpot. Ideal für Chatbot-Workflows, bei denen Supportanfragen oder Problemberichte automatisch protokolliert werden.

Type: POST URL:

https://api.hubapi.com/crm/v3/objects/tickets

Header:

Content-Type: application/json
Authorization: Bearer {token}

Body (Beispiel):

{
  "properties": {
    "hs_pipeline": "12345678",
    "hs_pipeline_stage": "12345678",
    "hs_ticket_priority": "LOW",
    "subject": "Deine XY Anfrage",
    "content": "Email: [email protected]",
    "melibo_chat_pdf_url": "@var{pdfUrl.url}"
  },
  "associations": [
    {
      "to": { "id": "@var{getContact.properties.hs_object_id.value}" },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 16
        }
      ]
    }
  ]
}

Response (Beispiel):

{
  "id": "987654321",
  "properties": {
    "hs_pipeline": "84623314",
    "hs_pipeline_stage": "196593108",
    "hs_ticket_priority": "LOW",
    "subject": "Deine Papershift Anfrage",
    "content": "Email: [email protected]",
    "melibo_chat_pdf_url": "https://example.com/chat.pdf",
    "createdate": "2024-06-04T10:20:30.000Z",
    "hs_object_id": "987654321"
  },
  "createdAt": "2024-06-04T10:20:30.000Z",
  "updatedAt": "2024-06-04T10:20:30.000Z",
  "archived": false,
  "associations": {
    "contacts": {
      "results": [
        {
          "id": "123456",
          "type": "contact_to_ticket"
        }
      ]
    }
  }
}

Variablen wie @var{pdfUrl.url} oder @var{getContact.properties.hs_object_id.value} stammen aus vorherigen API-Schritten oder Chatbot-Kontexten und werden dynamisch ersetzt.

---

✅ Zusammenfassung

Anwendungsfall	API-Methode	Endpunkt
Authentifizierung	–	Private Apps / OAuth 2.0
Kontakt erstellen	POST	/crm/v3/objects/contacts
Kontakt abrufen	GET	/contacts/v1/contact/email/{email}/profile
Ticket erstellen	POST	/crm/v3/objects/tickets

Du hast nun die Grundlagen zur Arbeit mit der HubSpot API kennengelernt! Mit deinem Access Token kannst du Kontakte, Tickets und weitere Objekte automatisiert verwalten und nahtlos in Systeme wie melibo integrieren.