Kundenportal-API

Bereiche

Mit der 1Tool API lesen und ändern Sie alle Daten Ihres 1Tool-Mandanten aus eigenen Programmen: Kontakte, Projekte, Angebote, Rechnungen, Termine und vieles mehr. Diese Seite führt Sie in wenigen Minuten zum ersten Aufruf. Links finden Sie alle Endpunkte, nach Fachbereichen geordnet.

Erste Schritte

Adresse der API: https://api.1tool.cloud/v1 – geschützt durch eine Web Application Firewall. Verwenden Sie sie für jede neue Anbindung; die Beispiele unten zeigen die Adresse der Seite, die Sie gerade lesen.

1. Token holen

Jeder Aufruf braucht einen Bearer-Token. Sie erhalten ihn mit E-Mail und Passwort eines 1Tool-Benutzers:

curl -X POST https://api.1tool.cloud/v1/auth/user \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email": "anna.berger@example.at", "password": "…"}'

Hat der Benutzer die Zwei-Faktor-Anmeldung aktiv, senden Sie zusätzlich code mit dem Code aus der Authenticator-App. Die Antwort enthält den Token in api_token.

• Ein Token gilt eine Woche. Danach antworten Aufrufe mit 401; melden Sie sich für einen neuen Token erneut an. Speichern Sie den Token, nicht das Passwort, und nie in einem Browser oder einer App, die Kunden einsehen können.
• Für eine dauerhafte Integration legen Sie einen eigenen Benutzer mit genau den Rechten an, die sie braucht. So können Sie ihn einzeln sperren und im Protokoll sehen, was er getan hat.
• Beenden Sie einen Token, wenn Sie ihn nicht mehr brauchen: siehe Sitzungen und Geräte im Bereich Anmeldung und Konto.

2. Ersten Aufruf machen

curl https://api.1tool.cloud/v1/contacts?per_page=5 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <Ihr Token>"

Sie sehen genau die Daten, die dieser Benutzer auch in 1Tool sehen darf. Rechte gelten in der API wie in der Oberfläche.

3. Den richtigen Endpunkt finden

Links stehen die Fachbereiche, darin die Ressourcen und darunter die einzelnen Aufrufe. Mit der Suche (Taste k mit Strg oder Cmd) finden Sie Endpunkte nach Name, Pfad oder Beschreibung. Bei jedem Aufruf können Sie rechts ein Code-Beispiel kopieren oder ihn mit Ihrem Token direkt ausprobieren.

Regeln, die für alle Endpunkte gelten

Kopfzeilen

Listen blättern

Listen kommen seitenweise als { "data": [...], "links": {...}, "meta": {...} }. Folgen Sie links.next, bis es leer ist.

• per_page bestimmt die Seitengröße, höchstens 1000. Größere Werte werden ohne Fehlermeldung auf 1000 gekürzt; die tatsächlich verwendete Größe steht in meta.per_page, die Gesamtzahl in meta.total.
• Für große Tabellen blättern Sie mit sort=id&filter[id_after]=<letzte id> statt mit hohen Seitennummern. Viele große Seiten hintereinander werden pro Mandant begrenzt.
• skip_total=1 spart das Zählen aller Treffer, wenn Sie die Gesamtzahl nicht brauchen.

Filtern

Filter heißen filter[<name>]=<wert>. Welche Filter ein Endpunkt kennt, steht bei seinen Parametern; ein unbekannter Filter wird mit einer Fehlermeldung abgelehnt, die die erlaubten Namen nennt. Mehrere Werte trennen Sie mit Komma: filter[id]=1,2,3.

Sortieren

sort=<spalte> aufsteigend, sort=-<spalte> absteigend. Achtung: Eine unbekannte Sortierspalte wird nicht abgelehnt: Die Liste kommt in der Standardreihenfolge, und der Antwort-Header X-Ignored-Sort nennt die ignorierte Spalte. Prüfen Sie den Namen gegen die Liste beim Endpunkt.

Verknüpfte Daten mitladen

include=contactGroups,assignedUsers lädt verknüpfte Datensätze in derselben Antwort mit. Welche Namen erlaubt sind, steht beim Parameter include des Endpunkts.

Datum und Zeit

Datum als Y-m-d, Datum mit Uhrzeit als Y-m-d H:i:s, ohne Zeitzone: Gemeint ist immer die Ortszeit Europe/Vienna, in Filtern, im Request-Body und in Antworten (einige ältere Felder liefern d.m.Y).

Rechnen Sie Werte vor dem Senden in Wiener Zeit um und lesen Sie Antworten als Wiener Zeit. Rund um die Zeitumstellung sind ganze Tage sicherer: Am letzten Sonntag im Oktober gibt es die Stunde von 02:00 bis 03:00 zweimal.

Aufruf-Limits

Über einer Grenze antwortet die API mit 429 Too Many Requests und dem Header Retry-After in Sekunden. Warten Sie so lange und machen Sie dann weiter; bei wiederholtem 429 verdoppeln Sie die Wartezeit jedes Mal. Ganze Tabellen lesen Sie mit filter[id_after] (siehe oben) Seite für Seite nacheinander, nicht parallel.

Eigene Felder

Mandantenspezifische Felder heißen custom_fields_0.<feld> (für alle Datensätze eines Typs) oder custom_fields_<n>.<feld> (nur für einen Untertyp, z. B. eine Terminkategorie). Laden mit include=custom_fields_0, schreiben mit {"custom_fields_0.i_1": 123}. Die Anzeigenamen liefert GET /api/custom-fields/<bereich>.

Für KI-Systeme

Claude und ChatGPT können 1Tool über unseren MCP-Connector direkt nutzen. Jeder Aufruf hat eine feste operationId (zum Beispiel contacts.list, invoices.get), über die ein Agent ihn eindeutig benennen kann.

• llms.txt listet jede Ressource mit einem Link auf ihre eigene kleine OpenAPI-Datei. Eine KI lädt so nur, was sie braucht, statt der ganzen Spezifikation.
• Dieser Leitfaden als Markdown zum Einfügen in einen Prompt oder eine Wissensdatenbank.
• Jede Ressourcenseite bietet ihren eigenen OpenAPI-Download; die vollständige Spezifikation ist oben links verlinkt.

Weitere Dokumentation

• Platzhalter in Vorlagen
• Workflows
• Echtzeit-Kanäle
• This documentation in English