Freshservice API Übersicht: Ein vollständiger Entwicklerleitfaden für 2026

Wenn Sie Integrationen mit Freshservice erstellen, müssen Sie dessen API-Funktionen verstehen. Ob Sie die Ticket-Erstellung automatisieren, Benutzerdaten synchronisieren oder benutzerdefinierte Dashboards erstellen, die Freshservice API bietet Ihnen programmgesteuerten Zugriff auf Ihre IT-Service-Management-Daten.

Lassen Sie uns aufschlüsseln, was die Freshservice API bietet, wie man sich authentifiziert, welche Endpunkte verfügbar sind und wie man innerhalb der Ratenbegrenzungen arbeitet. Wir werden uns auch ansehen, wie Tools wie eesel AI einige dieser Integrationen vereinfachen können, ohne Code von Grund auf neu zu schreiben.

Was ist die Freshservice API?

Die Freshservice API ist eine RESTful-Schnittstelle, mit der Sie programmgesteuert mit Ihrer Freshservice-Instanz interagieren können. Sie folgt den Standard-HTTP-Konventionen, verwendet JSON für den Datenaustausch und unterstützt die gesamte Bandbreite der CRUD-Operationen (Create, Read, Update, Delete).

Hier ist, was das in der Praxis bedeutet. Sie können:

• Ticket-Daten in externe Reporting-Tools ziehen
• Tickets automatisch aus Überwachungsalarmen erstellen
• Benutzerinformationen mit Ihrem Identity Provider synchronisieren
• Asset-Datensätze aus Discovery-Tools aktualisieren
• Benutzerdefinierte Portale oder mobile Apps erstellen

Freshservice bietet tatsächlich zwei API-Versionen an. Version 1 ist die Legacy-API, die noch funktionsfähig, aber eingeschränkt ist. Version 2 ist das, was Sie für neue Projekte verwenden sollten. Sie bietet höhere Ratenbegrenzungen, bessere Fehlerbehandlung und mehr Endpunkte. Die v2 API akzeptiert nur JSON und erfordert HTTPS-Verbindungen.

Freshservice gibt es auch in drei Varianten, jede mit leicht unterschiedlichem API-Verhalten:

• Freshservice: Die Standard-ITSM-Plattform
• Freshservice for Business Teams (FSBT): Entwickelt für Nicht-IT-Abteilungen wie HR oder Facility Management
• Freshservice for MSPs: Entwickelt für Managed Service Provider, die mehrere Kunden betreuen

Die Kern-API funktioniert in allen drei Varianten gleich, aber einige Endpunkte und Terminologien unterscheiden sich. Zum Beispiel verwenden MSPs "Contacts" anstelle von "Requesters" und "Clients" anstelle von "Workspaces".

Authentifizierungsmethoden

Bevor Sie API-Aufrufe tätigen können, müssen Sie sich authentifizieren. Freshservice bietet je nach Anwendungsfall einige Optionen.

API-Schlüssel-Authentifizierung (empfohlen)

Dies ist der einfachste und gebräuchlichste Ansatz. Sie generieren einen API-Schlüssel aus Ihrem Freshservice-Profil und fügen ihn dann in Ihre Anfragen mit Basic Auth ein.

So finden Sie Ihren API-Schlüssel:

1. Melden Sie sich in Ihrem Freshservice-Portal an
2. Klicken Sie auf Ihr Profilbild oben rechts
3. Gehen Sie zu Profileinstellungen
4. Ihr API-Schlüssel erscheint unter dem Abschnitt Passwort ändern

Sobald Sie Ihren Schlüssel haben, authentifizieren Sie sich, indem Sie ihn als Benutzernamen in einem Basic Auth Header übergeben, mit einer beliebigen Zeichenkette (konventionell "X") als Passwort. So sieht das in der Praxis aus:

curl -u "your_api_key:X" \
  -H "Content-Type: application/json" \
  -X GET \
  "https://yourdomain.freshservice.com/api/v2/tickets"

Oder in JavaScript:

const apiKey = "your_api_key_here";
const encodedKey = Buffer.from(apiKey + ":X").toString("base64");

fetch("https://yourdomain.freshservice.com/api/v2/tickets", {
  method: "GET",
  headers: {
    "Authorization": `Basic ${encodedKey}`,
    "Content-Type": "application/json"
  }
})
.then(response => response.json())
.then(data => console.log(data));

Benutzername und Passwort Authentifizierung

Sie können sich auch mit Ihren Freshservice-Anmeldedaten authentifizieren. Dies funktioniert genauso wie die API-Schlüssel-Authentifizierung, aber Sie übergeben stattdessen Ihre E-Mail-Adresse und Ihr Passwort:

curl -u "user@company.com:password" \
  -H "Content-Type: application/json" \
  -X GET \
  "https://yourdomain.freshservice.com/api/v2/tickets"

OAuth 2.0

Für Anwendungen, die im Namen von Benutzern agieren müssen (wie z. B. Marketplace-Apps), unterstützt Freshservice OAuth 2.0. Dies ist komplexer einzurichten, bietet aber eine bessere Sicherheit für benutzerorientierte Integrationen.

Sicherheits-Best Practices

Ein paar Dinge, die Sie beachten sollten:

• Speichern Sie API-Schlüssel sicher, übertragen Sie sie niemals in die Versionskontrolle
• Verwenden Sie HTTPS für alle Anfragen (v2 erfordert dies)
• Rotieren Sie API-Schlüssel regelmäßig
• Verwenden Sie die minimal erforderlichen Berechtigungen für Ihre Integration
• Erwägen Sie die Verwendung von Umgebungsvariablen für die Schlüsselspeicherung

Kern-API-Endpunkte und -Funktionen

Die Freshservice API deckt nahezu jede Funktion in der Plattform ab. Hier sind die wichtigsten Endpunkte, mit denen Sie arbeiten werden.

Tickets

Der Tickets-Endpunkt ist der am häufigsten verwendete. Sie können:

• Alle Tickets mit Filterung und Paginierung auflisten
• Neue Tickets programmgesteuert erstellen
• Ticket-Eigenschaften aktualisieren (Status, Priorität, Bearbeiter)
• Tickets löschen oder wiederherstellen
• Antworten und Notizen hinzufügen

Eine einfache Ticket-Erstellungsanfrage sieht wie folgt aus:

fetch("https://yourdomain.freshservice.com/api/v2/tickets", {
  method: "POST",
  headers: {
    "Authorization": "Basic " + btoa("api_key:X"),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "requester@example.com",
    subject: "New laptop request",
    description: "I need a new laptop for the upcoming project",
    priority: 2,
    status: 2
  })
});

Ticket-Eigenschaften verwenden numerische Werte für Status und Priorität:

Benutzer und Gruppen

Verwalten Sie Ihr Service-Desk-Team und Ihre Anfragenden:

• Agenten: IT-Mitarbeiter, die Tickets bearbeiten
• Anfragende: Mitarbeiter, die Tickets einreichen
• Gruppen: Teams, die bestimmte Tickettypen bearbeiten
• Abteilungen: Organisationsstruktur

Assets (Vermögenswerte)

Verfolgen und verwalten Sie IT-Assets während ihres gesamten Lebenszyklus:

• Asset-Datensätze erstellen und aktualisieren
• Assets mit Tickets verknüpfen
• Asset-Beziehungen und -Abhängigkeiten verwalten
• Asset-Wartung und -Verträge verfolgen

Änderungen und Probleme

Für ITIL-konformes Änderungsmanagement:

• Änderungsanforderungen erstellen
• Change-Genehmigungs-Workflows verwalten
• Änderungen mit Tickets und Problemen verknüpfen
• Implementierungsstatus verfolgen

Servicekatalog

Automatisieren Sie Serviceanfragen:

• Verfügbare Service-Elemente auflisten
• Serviceanfragen einreichen
• Genehmigungsstatus der Anfrage verfolgen
• Service Level Agreements verwalten

Konversationen

Bearbeiten Sie die Ticket-Kommunikation:

• Fügen Sie öffentliche Antworten hinzu, die für Anfragende sichtbar sind
• Fügen Sie private Notizen für interne Teams hinzu
• Hängen Sie Dateien an Konversationen an
• Leiten Sie Tickets an externe Parteien weiter

Ratenbegrenzungen und Best Practices

Freshservice legt Ratenbegrenzungen fest, um die Stabilität der Plattform zu gewährleisten. Diese variieren je nach Ihrem Plan und dem Zeitpunkt, an dem Ihr Konto erstellt wurde.

Ratenbegrenzungen nach Plan

Für Konten, die nach dem 1. September 2020 erstellt wurden:

Beachten Sie, dass dies kontoweite Limits sind, nicht pro Benutzer oder pro IP. Jeder API-Aufruf von Ihrem Konto zählt zum gleichen Kontingent.

Ratenbegrenzungs-Header

Jede API-Antwort enthält Header, die Ihren aktuellen Ratenbegrenzungsstatus anzeigen:

• X-RateLimit-Total: Das Gesamtlimit Ihres Kontos pro Minute
• X-RateLimit-Remaining: Verbleibende Anfragen im aktuellen Fenster
• X-RateLimit-Used-CurrentRequest: Wie viele Anfragen Ihr letzter Aufruf verbraucht hat
• Retry-After: Sekunden, die gewartet werden müssen, wenn Sie das Limit erreicht haben (erscheint nur bei 429 Antworten)

Umgang mit Ratenbegrenzungen

Wenn Sie das Limit erreichen, gibt die API einen 429-Statuscode zurück. Ihr Code sollte dies elegant behandeln:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response.json();
    }

    const retryAfter = response.headers.get('Retry-After') || Math.pow(2, retries);
    console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    retries++;
  }

  throw new Error('Maximum retries reached');
}

Paginierung

Listen-Endpunkte geben paginierte Ergebnisse zurück. Verwenden Sie den Parameter page, um zu navigieren:

curl -u "api_key:X" \
  "https://yourdomain.freshservice.com/api/v2/tickets?page=2&per_page=100"

Die v2 API unterstützt Seitengrößen von bis zu 100 Datensätzen. Implementieren Sie immer die Paginierung für Produktionsintegrationen, anstatt davon auszugehen, dass Sie alle Ergebnisse in einem Aufruf erhalten.

Häufige Anwendungsfälle für die Integration

Hier sind einige praktische Möglichkeiten, wie Unternehmen die Freshservice API nutzen:

Automatisierte Ticket-Erstellung: Überwachungstools wie Datadog oder PagerDuty können automatisch Tickets erstellen, wenn Alarme ausgelöst werden, um sicherzustellen, dass IT-Teams schnell auf Vorfälle reagieren.

Benutzerbereitstellung: Wenn neue Mitarbeiter eintreten, können HR-Systeme automatisch Freshservice-Konten erstellen und sie basierend auf ihrer Rolle den richtigen Abteilungen und Gruppen zuweisen.

Asset-Synchronisation: Discovery-Tools können Asset-Daten in die CMDB von Freshservice übertragen und so die Inventardatensätze ohne manuelle Eingabe aktuell halten.

Benutzerdefinierte Dashboards: Unternehmen ziehen Ticket-Metriken in Business-Intelligence-Tools wie Tableau oder Power BI für das Executive Reporting.

Chatbot-Integrationen: KI-gestützte Support-Tools können Tickets aus Chat-Konversationen erstellen und diese basierend auf der Inhaltsanalyse automatisch kategorisieren und weiterleiten.

E-Mail-Automatisierung: Eingehende E-Mails von bestimmten Domänen oder mit bestimmten Schlüsselwörtern können die Ticket-Erstellung mit vorausgefüllten Kategorien und Bearbeitern auslösen.

Erste Schritte mit Ihrem ersten API-Aufruf

Bereit, es selbst auszuprobieren? Hier ist eine Kurzanleitung.

Holen Sie sich zunächst Ihren API-Schlüssel aus Ihren Freshservice-Profileinstellungen. Öffnen Sie dann ein Terminal und führen Sie diesen cURL-Befehl aus (ersetzen Sie yourdomain und your_api_key):

curl -u "your_api_key:X" \
  -H "Content-Type: application/json" \
  -X GET \
  "https://yourdomain.freshservice.com/api/v2/tickets?page=1&per_page=1"

Wenn alles funktioniert, erhalten Sie eine JSON-Antwort mit Ihrem letzten Ticket.

Für die Erkundung ist Postman von unschätzbarem Wert. Erstellen Sie eine neue Anfrage, setzen Sie die Authentifizierung auf Basic Auth mit Ihrem API-Schlüssel als Benutzernamen und "X" als Passwort und beginnen Sie mit dem Testen von Endpunkten.

Freshworks bietet auch ein offizielles JavaScript/TypeScript SDK an, das die API-Interaktionen vereinfacht:

const { Freshservice } = require("@freshworks/api-sdk");
const fs = new Freshservice("yourdomain", "your_api_key");

// Get all tickets
const tickets = await fs.tickets.list();

Vereinfachung von Freshservice-Integrationen mit eesel AI

Das Erstellen von API-Integrationen von Grund auf erfordert Zeit und Engineering-Ressourcen. Wenn Sie Freshservice-Workflows automatisieren müssen, ohne Code zu schreiben, bietet eesel AI einen alternativen Ansatz.

Unsere Plattform verbindet sich direkt mit Freshservice und bietet KI-gestützte Automatisierung für gängige Aufgaben:

• AI Agent: Bearbeitet selbstständig Frontline-Support-Tickets und löst häufige Probleme ohne menschliches Zutun
• AI Copilot: Entwirft Antworten, die Ihre Agenten überprüfen und senden können, wodurch die Reaktionszeiten beschleunigt werden
• AI Triage: Taggt, leitet und priorisiert eingehende Tickets automatisch basierend auf dem Inhalt

Anstatt API-Aufrufe zu schreiben, um Tickets zu erstellen oder Felder zu aktualisieren, konfigurieren Sie Automatisierungsregeln in einfachem Deutsch. Zum Beispiel: "Wenn ein Ticket 'Passwort zurücksetzen' erwähnt und von einem VIP-Benutzer stammt, weisen Sie es der Senior-Support-Gruppe zu und markieren Sie es als hohe Priorität."

Die Einrichtung dauert Minuten statt Wochen. Sie verbinden Ihr Freshservice-Konto, und unsere KI lernt von Ihren bestehenden Tickets, Help-Center-Artikeln und Makros. Sie müssen keine API-Endpunkte zuordnen oder sich selbst um die Ratenbegrenzung kümmern.

Für Teams, die sowohl benutzerdefinierte API-Integrationen als auch KI-Automatisierung benötigen, ergänzen sich die Ansätze. Verwenden Sie die API für die Datensynchronisation und die System-zu-System-Kommunikation und eesel AI für die intelligente Ticketbearbeitung und das Verfassen von Antwortentwürfen.