So erstellen Sie Organisationen mit der Zendesk-API: Eine vollständige Anleitung

Organisationen sind eine der leistungsstärksten Funktionen von Zendesk für die Verwaltung von Kundenbeziehungen in großem Umfang. Sie ermöglichen es Ihnen, Benutzer zusammenzufassen, Tickets automatisch weiterzuleiten und die Sichtbarkeit von Support-Konversationen zu steuern. Während Sie Organisationen manuell über die Zendesk-Oberfläche erstellen können, liegt die wahre Stärke in der Automatisierung dieses Prozesses über die Zendesk API.

Egal, ob Sie von einer anderen Plattform migrieren, mit Ihrem CRM synchronisieren oder einen Self-Service-Anmeldefluss erstellen, das Wissen, wie Sie Organisationen über die Zendesk Organizations API erstellen, ist für jede ernsthafte Implementierung unerlässlich. Diese Anleitung führt Sie durch alles, was Sie wissen müssen, von der Authentifizierung bis zum Umgang mit Sonderfällen. Wenn Sie die Organisationsverwaltung über einfache API-Aufrufe hinaus automatisieren möchten, kann eesel AI den gesamten Workflow für Sie übernehmen.

Was Sie für den Anfang benötigen

Bevor Sie in den Code eintauchen, stellen Sie sicher, dass Sie diese Voraussetzungen erfüllt haben:

• Ein Zendesk-Konto mit Administratorzugriff. Nur Administratoren und Agenten mit benutzerdefinierten Rollen können Organisationen über die API erstellen.
• Ein API-Token. Sie müssen dieses in Ihrem Zendesk Admin Center unter Apps und Integrationen > APIs > Zendesk API generieren.
• Ihre Zendesk-Subdomain. Dies ist der erste Teil Ihrer Zendesk-URL (z. B. yourcompany in yourcompany.zendesk.com).
• Ein Tool zum Senden von HTTP-Anfragen. Wir zeigen Beispiele mit cURL, Python und JavaScript, also wählen Sie das, was für Ihren Stack funktioniert.

Die Zendesk API verwendet die Basisauthentifizierung (Basic Authentication) mit einer Kombination aus E-Mail-Adresse und API-Token. Dies ist sicherer als die Verwendung Ihres Passworts und ermöglicht es Ihnen, den Zugriff detailliert zu steuern.

Schritt 1: Generieren Sie Ihr Zendesk-API-Token

Ihr API-Token ist der Schlüssel, mit dem Ihr Code sich bei Zendesk authentifizieren kann. So erstellen Sie eines:

1. Melden Sie sich als Administrator bei Ihrem Zendesk-Konto an
2. Klicken Sie in der Seitenleiste auf das Symbol Admin Center
3. Navigieren Sie zu Apps und Integrationen > APIs > Zendesk API
4. Klicken Sie auf die Registerkarte Einstellungen
5. Aktivieren Sie Token-Zugriff, falls er noch nicht aktiviert ist
6. Klicken Sie auf das Pluszeichen (+), um ein neues Token hinzuzufügen
7. Geben Sie ihm einen beschreibenden Namen wie "Organization Management API"
8. Kopieren Sie das Token sofort (Zendesk zeigt es nur einmal an)

Bewahren Sie dieses Token sicher auf. Behandeln Sie es wie ein Passwort. Jeder, der Ihr Token besitzt, kann über die API auf Ihre Zendesk-Daten zugreifen.

Profi-Tipp: Erstellen Sie separate Token für verschiedene Integrationen, anstatt eines überall wiederzuverwenden. Dies erleichtert das Widerrufen des Zugriffs bei Bedarf, ohne andere Systeme zu beeinträchtigen.

Schritt 2: Verstehen Sie den Organisationsendpunkt

Die Organizations API folgt den REST-Konventionen. Um eine Organisation zu erstellen, senden Sie eine POST-Anfrage an:

https://{subdomain}.zendesk.com/api/v2/organizations

Der Anfragetext ist ein JSON-Objekt, das die Organisationseigenschaften enthält. So sieht eine minimale Erstellungsanfrage aus:

{
  "organization": {
    "name": "Acme Corporation"
  }
}

Das einzige erforderliche Feld ist name, und es muss in Ihrem gesamten Zendesk-Konto eindeutig sein. Sie dürfen keine Pipe-Zeichen (|) in den Namen aufnehmen, da die Anfrage sonst fehlschlägt.

Über die Grundlagen hinaus können Sie verschiedene nützliche Eigenschaften festlegen:

Die Authentifizierung erfolgt über HTTP Basic Auth. Kombinieren Sie Ihre E-Mail-Adresse mit /token: und Ihrem API-Token und Base64-kodieren Sie dann das Ergebnis. Der Header sieht wie folgt aus:

Authorization: Basic {base64_encoded_credentials}

Schritt 3: Erstellen Sie Ihre erste Organisation

Lassen Sie uns dies mit funktionierenden Codebeispielen in die Praxis umsetzen. Jedes Beispiel erstellt eine Organisation mit gängigen Feldern, die Sie tatsächlich verwenden würden.

Verwendung von cURL

SUBDOMAIN="yourcompany"
EMAIL="admin@yourcompany.com"
TOKEN="your_api_token_here"

curl -X POST "https://${SUBDOMAIN}.zendesk.com/api/v2/organizations" \
  -H "Content-Type: application/json" \
  -u "${EMAIL}/token:${TOKEN}" \
  -d '{
    "organization": {
      "name": "Acme Corporation",
      "domain_names": ["acme.com", "acmecorp.com"],
      "external_id": "CRM-12345",
      "tags": ["enterprise", "priority"],
      "details": "Enterprise customer since 2020"
    }
  }'

Verwendung von Python

import requests
import base64

subdomain = "yourcompany"
email = "admin@yourcompany.com"
token = "your_api_token_here"

credentials = base64.b64encode(
    f"{email}/token:{token}".encode()
).decode()

organization = {
    "organization": {
        "name": "Acme Corporation",
        "domain_names": ["acme.com", "acmecorp.com"],
        "external_id": "CRM-12345",
        "tags": ["enterprise", "priority"],
        "details": "Enterprise customer since 2020"
    }
}

response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/organizations",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Basic {credentials}"
    },
    json=organization
)

if response.status_code == 201:
    created_org = response.json()["organization"]
    print(f"Created organization ID: {created_org['id']}")
    print(f"Name: {created_org['name']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Verwendung von JavaScript/Node.js

const axios = require('axios');

// Configuration
const config = {
  subdomain: 'yourcompany',
  email: 'admin@yourcompany.com',
  token: 'your_api_token_here'
};

// Organization data
const organization = {
  organization: {
    name: 'Acme Corporation',
    domain_names: ['acme.com', 'acmecorp.com'],
    external_id: 'CRM-12345',
    tags: ['enterprise', 'priority'],
    details: 'Enterprise customer since 2020'
  }
};

// Make the request
axios.post(
  `https://${config.subdomain}.zendesk.com/api/v2/organizations`,
  organization,
  {
    headers: {
      'Content-Type': 'application/json'
    },
    auth: {
      username: `${config.email}/token`,
      password: config.token
    }
  }
)
.then(response => {
  const org = response.data.organization;
  console.log(`Created organization ID: ${org.id}`);
  console.log(`Name: ${org.name}`);
})
.catch(error => {
  console.error('Error:', error.response?.data || error.message);
});

Eine erfolgreiche Erstellung gibt HTTP 201 mit dem vollständigen Organisationsobjekt zurück, einschließlich des automatisch generierten Felds id, das Sie für zukünftige Aktualisierungen benötigen.

Schritt 4: Arbeiten Sie mit benutzerdefinierten Organisationsfeldern

Die meisten Zendesk-Implementierungen verwenden benutzerdefinierte Felder, um zusätzliche Organisationsdaten wie Kontostufen, Regionen oder CRM-IDs zu speichern. So arbeiten Sie über die API mit ihnen.

Zuerst müssen Sie wissen, welche benutzerdefinierten Felder vorhanden sind. Sie finden sie in Ihrem Zendesk Admin Center unter Objekte und Regeln > Organisationen > Felder oder rufen Sie sie über die API ab:

curl "https://{subdomain}.zendesk.com/api/v2/organization_fields" \
  -u "{email}/token:{token}"

Jedes benutzerdefinierte Feld hat einen eindeutigen Schlüssel (wie account_tier oder region). Wenn Sie eine Organisation erstellen oder aktualisieren, fügen Sie diese in das Objekt organization_fields ein:

{
  "organization": {
    "name": "Acme Corporation",
    "organization_fields": {
      "account_tier": "enterprise",
      "region": "north_america",
      "crm_id": "CRM-12345",
      "contract_value": 50000
    }
  }
}

Das Wertformat hängt vom Feldtyp ab:

• Textfelder: Zeichenfolgenwerte
• Dropdown-Felder: Der Options-Tag-Wert (nicht der Anzeigename)
• Numerische Felder: Zahlen (keine Zeichenfolgen)
• Datumsfelder: ISO 8601-Format (2024-01-15)
• Kontrollkästchenfelder: Boolesch (true oder false)

Häufiger Anwendungsfall: Synchronisieren von Organisationsdaten aus Ihrem CRM. Richten Sie einen Webhook oder einen geplanten Job ein, der Aktualisierungen an Zendesk überträgt, wenn sich die Kontodetails in Ihrem primären System ändern. Dadurch arbeiten Support-Agenten mit aktuellen Informationen.

Schritt 5: Behandeln Sie Fehler und Sonderfälle

Produktionscode muss mit Dingen umgehen, die schiefgehen. Hier sind die häufigsten Fehler, auf die Sie stoßen werden:

401 Nicht autorisiert

Dies bedeutet, dass Ihre Anmeldeinformationen ungültig sind. Überprüfen Sie Folgendes:

• Ihr API-Token ist korrekt und wurde nicht widerrufen
• Ihre E-Mail-Adresse stimmt mit dem Konto überein, dem das Token gehört
• Sie verwenden das richtige Format: email/token:token (beachten Sie den /token:-Teil)

422 Nicht verarbeitbare Entität

Die Anfrage wurde verstanden, konnte aber nicht verarbeitet werden. Häufige Ursachen:

• Doppelter Name: Organisationsnamen müssen eindeutig sein. Überprüfen Sie zuerst die vorhandenen Organisationen.
• Ungültige Zeichen: Namen dürfen keine Pipe-Zeichen (|) enthalten.
• Fehlende Pflichtfelder: Das Feld name ist obligatorisch.
• Ungültige benutzerdefinierte Feldwerte: Stellen Sie sicher, dass die Dropdown-Werte genau mit den definierten Optionen übereinstimmen.

429 Zu viele Anfragen

Sie haben das Ratenlimit von Zendesk erreicht. Die Organizations API erlaubt 700 Anfragen pro Minute. Wenn Sie Organisationen in großen Mengen erstellen müssen, fügen Sie Verzögerungen zwischen den Anfragen hinzu:

import time

for org_data in organizations:
    response = requests.post(url, json=org_data, auth=auth)
    if response.status_code == 429:
        # Wait and retry
        time.sleep(1)
        response = requests.post(url, json=org_data, auth=auth)
    # Process response...
    time.sleep(0.1)  # Be nice to the API

Bewährte Methode: Überprüfen Sie beim Erstellen von Integrationen immer die Antwortstatuscodes und implementieren Sie exponentielles Backoff für 429-Fehler. Protokollieren Sie fehlgeschlagene Anfragen, damit Sie sie später wiederholen können.

Automatisieren der Organisationsverwaltung mit eesel AI

Die manuelle Verwaltung von Organisationen ist nicht skalierbar. Wenn Ihr Kundenstamm wächst, wird die Synchronisierung von Zendesk-Organisationen mit Ihrem CRM, Abrechnungssystem und anderen Tools zu einer erheblichen betrieblichen Belastung.

Hier können wir helfen. Bei eesel AI haben wir einen KI-Teamkollegen entwickelt, der sich direkt in Zendesk integriert und organisationsbasierte Workflows automatisieren kann.

So verwenden unsere Kunden eesel AI mit Organisationen:

• Automatische Organisationszuweisung: Wenn ein Ticket eingeht, kann unsere KI den Anfragenden in Ihrem CRM nachschlagen, seine Organisation in Zendesk erstellen oder aktualisieren und das Ticket basierend auf den Organisationseigenschaften an das richtige Team weiterleiten.
• Intelligente Eskalation: Wir können benutzerdefinierte Organisationsfelder (wie Kontostufe oder SLA-Level) lesen und Tickets von Unternehmenskunden automatisch eskalieren.
• Organisationsbezogene Antworten: Unsere KI entwirft Antworten, die sich auf organisationsspezifische Details wie Vertragsbedingungen, dedizierte Account Manager oder frühere Probleme beziehen.

Im Gegensatz zum Erstellen benutzerdefinierter API-Integrationen lernt eesel AI aus Ihren vorhandenen Daten und Workflows. Sie beschreiben in einfachem Deutsch, was Sie möchten (z. B. "Wenn die Organisationsstufe Enterprise ist, setzen Sie den Account Manager auf CC"), und unsere KI übernimmt die API-Aufrufe, die Fehlerbehandlung und die Logik.

Sie können mit unserem KI-Copiloten beginnen, der Antworten für die Überprüfung durch Agenten entwirft, und dann auf die vollständige Automatisierung umsteigen, wenn Sie Vertrauen aufbauen. Die meisten Teams sehen innerhalb von zwei Monaten eine Amortisation.

Beginnen Sie mit dem Erstellen mit der Zendesk Organizations API

Sie haben jetzt alles, was Sie zum programmgesteuerten Erstellen und Verwalten von Organisationen in Zendesk benötigen. Lassen Sie uns die wichtigsten Schritte zusammenfassen:

1. Generieren Sie ein API-Token in Ihrem Zendesk Admin Center
2. Strukturieren Sie Ihre POST-Anfrage an /api/v2/organizations mit den Organisationsdaten
3. Verarbeiten Sie die JSON-Antwort, um die ID der erstellten Organisation zu erhalten
4. Verwenden Sie benutzerdefinierte Felder, um organisationsspezifische Daten zu speichern
5. Implementieren Sie eine ordnungsgemäße Fehlerbehandlung für Produktionscode

Die Organizations API ist nur der Anfang. Sie können auch Organisationen aktualisieren, Duplikate zusammenführen, Organisationsmitgliedschaften verwalten und organisationsbasierte Geschäftsregeln einrichten.

Für fortgeschrittene Anwendungsfälle wie Massenimporte oder bidirektionale Synchronisierung mit anderen Systemen sollten Sie überlegen, ob eine KI-gestützte Lösung Ihrem Team Zeit sparen könnte. Testen Sie eesel AI 7 Tage lang kostenlos und sehen Sie, wie die Automatisierung Ihre Support-Abläufe verändern kann.