# 1Tool API 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: ```bash 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 ```bash curl https://api.1tool.cloud/v1/contacts?per_page=5 \ -H "Accept: application/json" \ -H "Authorization: Bearer " ``` 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. ## Die Bereiche - **Anmeldung und Konto** – Wie man sich als Benutzer oder Kontakt anmeldet, Tokens erhält, Zwei-Faktor-Anmeldung einrichtet und Sitzungen verwaltet. - **Kontakte** – Kunden, Interessenten, Lieferanten und Personen mit ihren Adressen, Gruppen, Beziehungen, Notizen und Besuchen. - **Vertrieb** – Vom Lead über die Verkaufschance bis zum angenommenen Angebot. - **Projekte und Aufgaben** – Projekte mit Phasen, Mitgliedern und Produkten, dazu Aufgaben, Boards, Checklisten und die Ressourcenplanung. - **Zeit und Personal** – Zeiterfassung, Urlaub, Arbeitszeiten, Schichten, Stellenausschreibungen und Schulungen. - **Kalender, Kurse und Umfragen** – Termine und Einladungen, Seminare und Kurse, Zertifikate, Raumbuchung und Umfragen. - **Finanzen** – Rechnungen und Mahnungen, Eingangsrechnungen und Kosten, Buchhaltung, Bank und Budgets. - **Produkte, Shop und Lager** – Produktkatalog mit Varianten und Preisen, Bestellungen, Onlineshop und Lagerverwaltung. - **Kommunikation** – E-Mail, Newsletter, Chat, Telefonie, SMS und Benachrichtigungen. - **Dateien und Dokumente** – Dateien und Ordner mit Freigaben, PDF- und Excel-Erzeugung, Vorlagen und Vorschauen. - **Auswertungen** – Berichte, Listen, Diagramme, Statistiken und Dashboard-Bausteine. - **Versicherung und Provisionen** – Branchenmodul für Versicherungsmakler: Anträge, Produkte, Sparten, Schäden und Provisionsabrechnung. - **Verwaltung und Einstellungen** – Benutzer und Rechte, eigene Felder und Masken, Workflows, Webhooks und Einstellungen des Mandanten. - **Nachschlagedaten und Hilfsdienste** – Länder, Sprachen, Vorwahlen, Symbole, Geokodierung und Schnellsuche. ## Regeln, die für alle Endpunkte gelten ### Kopfzeilen | Kopfzeile | Wann | Wert | | --- | --- | --- | | `Authorization` | immer, außer bei der Anmeldung | `Bearer ` | | `Accept` | empfohlen | `application/json` | | `X-Tenant` | nur für Kontakt-Logins und öffentliche Endpunkte | UUID des Mandanten. Für Benutzer-Tokens nicht nötig: der Token kennt seinen Mandanten. | ### 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]=` 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[]=`. 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=` aufsteigend, `sort=-` 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`). | Wert | Bedeutet | In UTC | | --- | --- | --- | | `2026-07-01 14:00:00` | 14:00 Sommerzeit (MESZ) | `2026-07-01T12:00:00Z` | | `2026-12-01 14:00:00` | 14:00 Winterzeit (MEZ) | `2026-12-01T13:00:00Z` | 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 | Was | Grenze | | --- | --- | | Alle Aufrufe eines Benutzers oder Kontakts | 1.500 pro Minute (manche Mandanten haben ein kleineres Budget) | | E-Mail-Versand (`emails/send`) | 100 pro Minute | | Massen-Lesen (`per_page` ab 500, ab Seite 21) | pro Mandant 10 Seiten pro Minute von 07:00 bis 19:00, nachts 30, höchstens 2 gleichzeitig | Ü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.` (für alle Datensätze eines Typs) oder `custom_fields_.` (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/`. ## 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](https://api.1tool.cloud/v1/llms.txt?lang=de)** 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](https://api.1tool.cloud/v1/public/docs.md?lang=de)** 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](https://api.1tool.cloud/docs/placeholders) - [Workflows](https://api.1tool.cloud/docs/workflows) - [Echtzeit-Kanäle](https://api.1tool.cloud/docs/channels) - [This documentation in English](https://api.1tool.cloud/v1/docs)