{ "openapi": "3.1.0", "info": { "title": "E-Signing.io API", "version": "1.0.0", "description": "REST-API für Dokumente, Sendungen, ausgefüllte Inhalte, Kontakte und Eigenschaften.\n\n**Authentifizierung:** Workspace-API-Key im Header `Authorization: Bearer esk_live_…` (alternativ `X-API-Key`).\nKeys werden in der App unter *Automationen → API* erstellt und sind fest an einen Workspace gebunden.\n\n**Ratelimit:** 10 Anfragen pro Sekunde je Key (Burst 40). Bei Überschreitung antwortet die API mit `429`.\n\n**Formate:** Alle Zeitangaben sind ISO-8601-UTC-Strings. Listen unterstützen `limit` und `offset`." }, "servers": [ { "url": "https://e-signing.io/api/public/v1", "description": "Produktion" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Workspace-API-Key (`esk_live_…`)." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } } } }, "tags": [ { "name": "Allgemein", "description": "Verbindung prüfen." }, { "name": "Dokumente", "description": "Vorlagen und Dokumente inkl. Felder und Platzhalter." }, { "name": "Sendungen", "description": "Versendete Dokumente, Status, ausgefüllte Inhalte und Audit-Trail." }, { "name": "Kontakte", "description": "Kontakte lesen, anlegen, aktualisieren und löschen." }, { "name": "Eigenschaften", "description": "Benutzerdefinierte Kontaktfelder und Gruppen." }, { "name": "Rückfragen", "description": "Rückfragen und deren Antworten." }, { "name": "Webhooks", "description": "REST-Hooks für Zapier & Co. — Ereignisse abonnieren." } ], "paths": { "/me": { "get": { "tags": [ "Allgemein" ], "summary": "Verbindung testen", "description": "Gibt den Workspace zurück, zu dem der API-Key gehört. Ideal als Test-Aufruf in Zapier & Co.", "responses": { "200": { "description": "Workspace-Kontext", "content": { "application/json": { "example": { "workspace": { "id": "0f3f…", "name": "Musterkanzlei", "slug": "musterkanzlei", "plan": "payg" }, "key_name": "Zapier", "api_version": "v1" } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/documents": { "get": { "tags": [ "Dokumente" ], "summary": "Dokumente auflisten", "parameters": [ { "name": "limit", "in": "query", "description": "Anzahl der Einträge (1–200, Standard 50).", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "description": "Versatz für die Paginierung.", "schema": { "type": "integer", "default": 0 } }, { "name": "updated_since", "in": "query", "description": "Nur Einträge, die seit diesem Zeitpunkt geändert wurden (ISO 8601 oder ms).", "schema": { "type": "string", "format": "date-time" } }, { "name": "search", "in": "query", "description": "Freitextsuche im Dokumentnamen.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Liste von Dokumenten", "content": { "application/json": { "example": { "data": [ { "id": "d_2k39fjs0", "name": "Vorbereitungsvertrag", "kind": "document", "language": "de", "folder_id": null, "status": "draft", "signer_count": 1, "password_protected": false, "placeholders": [ "vorname", "nachname" ], "fields": [ { "id": "f_abc123", "type": "text", "label": "Kundennummer", "required": true, "external_id": "kdnr", "assigned_recipient_index": null } ], "created_at": "2026-05-04T10:00:00.000Z", "updated_at": "2026-07-19T08:22:00.000Z" } ], "total": 12, "limit": 50, "offset": 0 } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/documents/{id}": { "get": { "tags": [ "Dokumente" ], "summary": "Dokument abrufen", "description": "Wie die Liste, zusätzlich mit `blocks` (Inhaltsstruktur) und `theme`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dokument-ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dokument-Detail", "content": { "application/json": { "example": { "data": { "id": "d_2k39fjs0", "name": "Vorbereitungsvertrag", "placeholders": [ "vorname" ], "fields": [], "blocks": [ { "id": "b_1", "type": "heading", "content": "Vertrag" } ], "theme": { "id": "vapor" } } } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "404": { "description": "Nicht gefunden.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Nicht gefunden." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/shipments": { "get": { "tags": [ "Sendungen" ], "summary": "Sendungen auflisten", "parameters": [ { "name": "limit", "in": "query", "description": "Anzahl der Einträge (1–200, Standard 50).", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "description": "Versatz für die Paginierung.", "schema": { "type": "integer", "default": 0 } }, { "name": "updated_since", "in": "query", "description": "Nur Einträge, die seit diesem Zeitpunkt geändert wurden (ISO 8601 oder ms).", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "description": "Filter auf den Aktivitätsstatus.", "schema": { "type": "string", "enum": [ "sent", "opened", "signed", "expired", "revoked" ] } }, { "name": "document_id", "in": "query", "description": "Nur Sendungen dieses Dokuments.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "description": "`true`, um archivierte Sendungen einzuschließen.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Liste von Sendungen", "content": { "application/json": { "example": { "data": [ { "id": "s_8fjw02kd", "document_id": "d_2k39fjs0", "document_name": "Vorbereitungsvertrag", "status": "sent", "activity_status": "opened", "channel": "email", "sign_mode": "sequential", "signature_level": "fes", "password_protected": false, "folder_id": null, "owner_name": "Max Mustermann", "owner_email": "max@firma.de", "created_at": "2026-07-20T09:12:44.000Z", "expires_at": "2026-08-03T09:12:44.000Z", "archived_at": null, "revoked_at": null, "final_pdf_ready": true, "sealed": true, "recipients": [ { "id": "r_1", "link_id": "lnk_92hs71", "position": 0, "name": "Erika Beispiel", "email": "erika@example.com", "phone": null, "company": null, "status": "opened", "delivery_status": "delivered", "last_error": null, "sent_at": "2026-07-20T09:12:45.000Z", "expires_at": "2026-08-03T09:12:44.000Z", "signed_at": null, "view_count": 3, "last_viewed_at": "2026-07-21T14:02:10.000Z" } ] } ], "total": 41, "limit": 50, "offset": 0 } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } }, "post": { "tags": [ "Sendungen" ], "summary": "Versand auslösen", "description": "Versendet ein Dokument an einen oder mehrere Empfänger. Empfänger können direkt (`recipients`), über bestehende Kontakte (`contact_ids`) oder über Kontaktgruppen (`group_ids`) angegeben werden — Kombinationen sind erlaubt. Der Versand läuft über die interne Warteschlange: die Antwort enthält bereits die Links, noch offene Empfänger werden automatisch nachversendet.", "requestBody": { "required": true, "content": { "application/json": { "example": { "document_id": "d_2k39fjs0", "channel": "email", "recipients": [ { "name": "Erika Beispiel", "email": "erika@example.com", "company": "Beispiel GmbH" } ], "contact_ids": [], "group_ids": [], "placeholders": { "vorname": "Erika", "nachname": "Beispiel" }, "field_values": { "f_abc123": "KD-1024" }, "expires_in_days": 14, "signature_level": "ees", "password": null, "message": "Anbei Ihr Vertrag zur Unterschrift." } } } }, "responses": { "201": { "description": "Sendung angelegt", "content": { "application/json": { "example": { "data": { "id": "s_8fjw02kd", "document_id": "d_2k39fjs0", "document_name": "Vorbereitungsvertrag", "status": "sent", "activity_status": "opened", "channel": "email", "sign_mode": "sequential", "signature_level": "fes", "password_protected": false, "folder_id": null, "owner_name": "Max Mustermann", "owner_email": "max@firma.de", "created_at": "2026-07-20T09:12:44.000Z", "expires_at": "2026-08-03T09:12:44.000Z", "archived_at": null, "revoked_at": null, "final_pdf_ready": true, "sealed": true, "recipients": [ { "id": "r_1", "link_id": "lnk_92hs71", "position": 0, "name": "Erika Beispiel", "email": "erika@example.com", "phone": null, "company": null, "status": "opened", "delivery_status": "delivered", "last_error": null, "sent_at": "2026-07-20T09:12:45.000Z", "expires_at": "2026-08-03T09:12:44.000Z", "signed_at": null, "view_count": 3, "last_viewed_at": "2026-07-21T14:02:10.000Z" } ] }, "dispatch": { "sent": 1, "failed": 0, "remaining": 0 } } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "404": { "description": "Nicht gefunden.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Nicht gefunden." } } } } }, "422": { "description": "Ungültige Eingabe.", "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "Mindestens ein Empfänger ist erforderlich." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Webhook-Abos auflisten", "responses": { "200": { "description": "Liste der Abos", "content": { "application/json": { "example": { "data": [ { "id": "3f2a…", "event": "shipment.completed", "target_url": "https://hooks.zapier.com/hooks/catch/123/abc/", "is_active": true, "delivery_count": 12, "failure_count": 0, "last_delivered_at": "2026-07-21T14:02:10.000Z", "last_error": null, "created_at": "2026-07-01T09:00:00.000Z" } ], "events": [ "shipment.sent", "shipment.opened", "shipment.signed", "shipment.completed", "shipment.expired", "shipment.delivery_failed", "contact.created", "inquiry.answered" ] } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Webhook abonnieren (REST Hook)", "description": "Legt ein Abo an. Bei jedem Ereignis sendet die API einen POST an `target_url`. Die Antwort enthält einmalig das `secret`: jede Zustellung trägt den Header `X-Esigning-Signature: sha256=` über `.`. Antwortet das Ziel mit `410 Gone`, wird das Abo automatisch deaktiviert (Zapier-Konvention).", "requestBody": { "required": true, "content": { "application/json": { "example": { "event": "shipment.completed", "target_url": "https://hooks.zapier.com/hooks/catch/123/abc/" } } } }, "responses": { "201": { "description": "Abo angelegt", "content": { "application/json": { "example": { "data": { "id": "3f2a…", "event": "shipment.completed", "target_url": "https://hooks.zapier.com/hooks/catch/123/abc/", "is_active": true, "delivery_count": 12, "failure_count": 0, "last_delivered_at": "2026-07-21T14:02:10.000Z", "last_error": null, "created_at": "2026-07-01T09:00:00.000Z", "secret": "a1b2c3…" } } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Abo abrufen", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook-ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Abo", "content": { "application/json": { "example": { "data": { "id": "3f2a…", "event": "shipment.completed", "target_url": "https://hooks.zapier.com/hooks/catch/123/abc/", "is_active": true, "delivery_count": 12, "failure_count": 0, "last_delivered_at": "2026-07-21T14:02:10.000Z", "last_error": null, "created_at": "2026-07-01T09:00:00.000Z" } } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "404": { "description": "Nicht gefunden.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Nicht gefunden." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Abo entfernen (unsubscribe)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook-ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Abo entfernt", "content": { "application/json": { "example": { "data": { "id": "w_1", "deleted": true } } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "404": { "description": "Nicht gefunden.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Nicht gefunden." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/shipments/{id}": { "get": { "tags": [ "Sendungen" ], "summary": "Sendung abrufen", "description": "`id` akzeptiert die Sendungs-ID, die interne UUID oder eine Empfänger-Link-ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sendungs-ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sendungs-Detail", "content": { "application/json": { "example": { "data": { "id": "s_8fjw02kd", "document_id": "d_2k39fjs0", "document_name": "Vorbereitungsvertrag", "status": "sent", "activity_status": "opened", "channel": "email", "sign_mode": "sequential", "signature_level": "fes", "password_protected": false, "folder_id": null, "owner_name": "Max Mustermann", "owner_email": "max@firma.de", "created_at": "2026-07-20T09:12:44.000Z", "expires_at": "2026-08-03T09:12:44.000Z", "archived_at": null, "revoked_at": null, "final_pdf_ready": true, "sealed": true, "recipients": [ { "id": "r_1", "link_id": "lnk_92hs71", "position": 0, "name": "Erika Beispiel", "email": "erika@example.com", "phone": null, "company": null, "status": "opened", "delivery_status": "delivered", "last_error": null, "sent_at": "2026-07-20T09:12:45.000Z", "expires_at": "2026-08-03T09:12:44.000Z", "signed_at": null, "view_count": 3, "last_viewed_at": "2026-07-21T14:02:10.000Z" } ] } } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "404": { "description": "Nicht gefunden.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Nicht gefunden." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/shipments/{id}/fields": { "get": { "tags": [ "Sendungen" ], "summary": "Ausgefüllte Inhalte abrufen", "description": "Alle vom Empfänger ausgefüllten Feldwerte inkl. Label, Typ und `external_id` sowie die eingesetzten `{{platzhalter}}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sendungs-ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ausgefüllte Inhalte je Empfänger", "content": { "application/json": { "example": { "shipment_id": "s_8fjw02kd", "document_name": "Vorbereitungsvertrag", "data": [ { "recipient_id": "r_1", "recipient_name": "Erika Beispiel", "recipient_email": "erika@example.com", "status": "signed", "signed_at": "2026-07-22T10:04:00.000Z", "placeholders": { "vorname": "Erika" }, "fields": [ { "field_id": "f_abc123", "external_id": "kdnr", "label": "Kundennummer", "type": "text", "required": true, "value": "10023" }, { "field_id": "f_pay01", "external_id": null, "label": "Zahlungsplan", "type": "payment", "required": true, "value": { "variantId": "pv_monatlich", "extras": { "rate": "3" } } } ] } ] } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "404": { "description": "Nicht gefunden.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Nicht gefunden." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/shipments/{id}/events": { "get": { "tags": [ "Sendungen" ], "summary": "Audit-Trail abrufen", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sendungs-ID.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Anzahl der Ereignisse (max. 500).", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Ereignisse, neueste zuerst", "content": { "application/json": { "example": { "data": [ { "id": "e_92k1", "type": "signed", "at": "2026-07-22T10:04:00.000Z", "recipient_id": "r_1", "actor": { "name": "Erika Beispiel", "ip": "203.0.113.7" } } ] } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "404": { "description": "Nicht gefunden.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Nicht gefunden." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/contacts": { "get": { "tags": [ "Kontakte" ], "summary": "Kontakte auflisten", "parameters": [ { "name": "limit", "in": "query", "description": "Anzahl der Einträge (1–200, Standard 50).", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "description": "Versatz für die Paginierung.", "schema": { "type": "integer", "default": 0 } }, { "name": "updated_since", "in": "query", "description": "Nur Einträge, die seit diesem Zeitpunkt geändert wurden (ISO 8601 oder ms).", "schema": { "type": "string", "format": "date-time" } }, { "name": "search", "in": "query", "description": "Suche in Name, E-Mail, Firma, Telefon.", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Exakte E-Mail-Adresse.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Liste von Kontakten", "content": { "application/json": { "example": { "data": [ { "id": "c_9fj20dk1", "name": "Erika Beispiel", "email": "erika@example.com", "phone": "+4915112345678", "company": "Beispiel GmbH", "position": "Einkauf", "notes": null, "custom": { "vertrieb.quelle": "Website" }, "group_ids": [ "kunden" ], "created_at": "2026-06-02T08:00:00.000Z", "updated_at": "2026-07-18T11:30:00.000Z" } ], "total": 320, "limit": 50, "offset": 0 } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } }, "post": { "tags": [ "Kontakte" ], "summary": "Kontakt anlegen oder aktualisieren", "description": "Upsert: Gibt es bereits einen Kontakt mit derselben `email` (oder `id`), wird er aktualisiert; `custom` wird zusammengeführt. Unbekannte Gruppen in `group_ids` werden automatisch angelegt.", "requestBody": { "required": true, "content": { "application/json": { "example": { "email": "erika@example.com", "name": "Erika Beispiel", "phone": "+4915112345678", "company": "Beispiel GmbH", "position": "Einkauf", "notes": "Über Zapier importiert", "custom": { "vertrieb.quelle": "Website" }, "group_ids": [ "kunden" ] } } } }, "responses": { "200": { "description": "Kontakt aktualisiert", "content": { "application/json": { "example": { "data": { "id": "c_9fj20dk1", "name": "Erika Beispiel", "email": "erika@example.com", "phone": "+4915112345678", "company": "Beispiel GmbH", "position": "Einkauf", "notes": null, "custom": { "vertrieb.quelle": "Website" }, "group_ids": [ "kunden" ], "created_at": "2026-06-02T08:00:00.000Z", "updated_at": "2026-07-18T11:30:00.000Z" } } } } }, "201": { "description": "Kontakt angelegt", "content": { "application/json": { "example": { "data": { "id": "c_9fj20dk1", "name": "Erika Beispiel", "email": "erika@example.com", "phone": "+4915112345678", "company": "Beispiel GmbH", "position": "Einkauf", "notes": null, "custom": { "vertrieb.quelle": "Website" }, "group_ids": [ "kunden" ], "created_at": "2026-06-02T08:00:00.000Z", "updated_at": "2026-07-18T11:30:00.000Z" } } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "422": { "description": "Ungültige Eingabe.", "content": { "application/json": { "example": { "error": { "code": "invalid_request", "message": "email oder id erforderlich." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/contacts/{id}": { "get": { "tags": [ "Kontakte" ], "summary": "Kontakt abrufen", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kontakt-ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Kontakt", "content": { "application/json": { "example": { "data": { "id": "c_9fj20dk1", "name": "Erika Beispiel", "email": "erika@example.com", "phone": "+4915112345678", "company": "Beispiel GmbH", "position": "Einkauf", "notes": null, "custom": { "vertrieb.quelle": "Website" }, "group_ids": [ "kunden" ], "created_at": "2026-06-02T08:00:00.000Z", "updated_at": "2026-07-18T11:30:00.000Z" } } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "404": { "description": "Nicht gefunden.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Nicht gefunden." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } }, "delete": { "tags": [ "Kontakte" ], "summary": "Kontakt löschen", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Kontakt-ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Gelöscht", "content": { "application/json": { "example": { "deleted": true, "id": "c_9fj20dk1" } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/contact-fields": { "get": { "tags": [ "Eigenschaften" ], "summary": "Eigenschaften auflisten", "description": "Alle benutzerdefinierten Kontaktfelder samt Haupteigenschaften (Gruppen). Der `key` ist der Schlüssel im `custom`-Objekt eines Kontakts.", "responses": { "200": { "description": "Eigenschaften", "content": { "application/json": { "example": { "groups": [ { "id": "g_1", "name": "Vertrieb", "order": 0 } ], "fields": [ { "id": "cf_1", "key": "vertrieb.quelle", "label": "Quelle", "type": "select", "options": [ "Website", "Empfehlung" ], "group_id": "g_1", "group_name": "Vertrieb" } ] } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/contact-groups": { "get": { "tags": [ "Eigenschaften" ], "summary": "Kontaktgruppen auflisten", "responses": { "200": { "description": "Gruppen", "content": { "application/json": { "example": { "data": [ { "id": "kunden", "name": "Kunden", "created_at": "2026-04-01T10:00:00.000Z" } ] } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } }, "/inquiries": { "get": { "tags": [ "Rückfragen" ], "summary": "Rückfragen auflisten", "parameters": [ { "name": "limit", "in": "query", "description": "Anzahl der Einträge (1–200, Standard 50).", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "description": "Versatz für die Paginierung.", "schema": { "type": "integer", "default": 0 } }, { "name": "updated_since", "in": "query", "description": "Nur Einträge, die seit diesem Zeitpunkt geändert wurden (ISO 8601 oder ms).", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "description": "Statusfilter.", "schema": { "type": "string", "enum": [ "open", "answered", "closed", "archived" ] } } ], "responses": { "200": { "description": "Rückfragen", "content": { "application/json": { "example": { "data": [ { "id": "6f0…", "shipment_id": "s_8fjw02kd", "recipient_id": "r_1", "recipient_name": "Erika Beispiel", "recipient_email": "erika@example.com", "document_name": "Vorbereitungsvertrag", "title": "Passt der Termin?", "status": "answered", "answer_options": [ "Ja" ], "answer_text": "Bitte Montag anrufen.", "answer_phone": "+4915112345678", "answered_at": "2026-07-23T12:00:00.000Z", "created_at": "2026-07-22T10:10:00.000Z" } ], "total": 4, "limit": 50, "offset": 0 } } } }, "401": { "description": "API-Key fehlt oder ist ungültig.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "invalid_request", "rate_limited", "method_not_allowed", "server_error" ] }, "message": { "type": "string" } } } } }, "example": { "error": { "code": "unauthorized", "message": "Ungültiger oder widerrufener API-Key." } } } } }, "429": { "description": "Ratelimit überschritten.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Zu viele Anfragen. Bitte kurz warten." } } } } } } } } } }