Public REST API: ContractHero programmatisch ansteuern

Über die ContractHero Public REST API integrieren Sie ContractHero in Ihre eigenen Systeme und Workflows. Sie greifen auf Organisationen, Verträge, Kontakte und Aufgaben zu — lesen, anlegen, aktualisieren. Damit bauen Sie eigene Integrationen, Migrationen oder Reporting-Pipelines.

Ihr Vorteil

Während Webhooks ContractHero-Events an Ihre Systeme pushen, holt die REST API umgekehrt Daten und Aktionen ab oder löst sie aus. Typische Use-Cases:

Bulk-Import von Bestandsverträgen aus Altsystemen.
Reverse-Sync aus dem CRM oder ERP zurück nach ContractHero.
Reporting & BI: Vertragsdaten in BigQuery, Snowflake oder Looker spiegeln.
Eigene UI: Vertragsanlage aus Ihrer internen Anwendung heraus.

Statt CSV-Exporten und manuellem Hochladen läuft alles über standardisierte REST-Calls.

Voraussetzungen

Die REST API ist ab dem Professional-Plan verfügbar (Professional, Enterprise).
Die Aktivierung läuft über Ihr Customer-Experience-Team.
Entwickler-Know-how auf Ihrer Seite: REST, JSON, HTTP-Header, idealerweise Erfahrung mit OpenAPI-Spezifikationen.

So funktioniert's

1. Dokumentation öffnen

Die vollständige API-Doku finden Sie unter:

https://api.contracthero.com/docs

Format: OpenAPI 3.0.0, Version v1.0.0. Über „Download OpenAPI Document" laden Sie die Spec herunter und importieren sie in Tools wie Postman, Insomnia oder Ihren Code-Generator.

2. API-Zugang aktivieren lassen

Kontaktieren Sie uns über den ContractHero-Webchat oder per E-Mail an support@contracthero.com. Halten Sie folgende Infos bereit:

Ihren Use-Case in einem Satz.
Wer der technische Ansprechpartner für die Integration ist.
Ob Sie Lese- oder Schreibzugriff benötigen.

Wir richten den Zugang gemeinsam mit Ihnen ein und übergeben die nötigen Zugangsdaten direkt an Ihren technischen Ansprechpartner.

3. Erste Anfrage: Organisationen auflisten

Sobald der Zugang aktiv ist, holen Sie alle Organisationen, auf die Sie Zugriff haben:

GET /public/organizations

In der Antwort finden Sie die organizationId und teamId, die Sie für die weiteren Endpoints brauchen.

4. Vertrag anlegen (Beispiel)

POST /public/organizations/{organizationId}/teams/{teamId}/contracts
Content-Type: application/json

Body (gekürzt):

{
  "categoryId": "…",
  "propertyName": { … },
  "partnerCompany": { "$create": { "name": "Neuer Vertragspartner" } }
}

Erfolgreiche Antwort: HTTP 201 mit dem angelegten Vertrags-Objekt (id, category, status, createdAt, updatedAt, partnerCompany).

Verfügbare Endpoint-Gruppen

Bereich	Wesentliche Endpoints
Organizations	GET all organizations, GET organization, GET teams, GET categories, GET datapoints, GET contact datapoints, GET contact-types
Contracts	GET all contracts, POST create contract, PATCH update contract, GET single contract, GET signers, POST add document, GET documents, POST start signature process, GET document
Contacts	GET, POST, PATCH — Kontakte und deren Datapoints
Tasks	GET, POST, PATCH — Aufgabenverwaltung
Models	Sub-Schemata der API (Datenmodelle wie ContractDTO, AmountDatapointDTO)

Die vollständige Liste mit Path Parameters, Request Bodies, Response-Schemata und Beispielen finden Sie in der Live-Doku.

Häufige Fragen

Welche Pläne enthalten die REST API?

Ab Professional (Professional, Enterprise).

Wie bekomme ich Zugang?

Über das Customer-Experience-Team. Schreiben Sie uns an support@contracthero.com — wir richten den Zugang nach kurzer Use-Case-Abstimmung gemeinsam ein.

Ist die API REST oder GraphQL?

REST. Resource-orientierte URLs, JSON-Bodies, Standard-HTTP-Verben (GET, POST, PATCH), Standard-HTTP-Statuscodes.

Welche Sub-Ressourcen sind verfügbar?

Verträge inkl. Dokumenten-Upload, Signatur-Prozess starten, Signers abfragen, Vertragsdokumente lesen. Kontakte inkl. Datapoints. Aufgaben (Tasks).

Wie verhält sich die API bei Berechtigungen?

Der Zugang wirkt im Kontext der zugewiesenen Organisation und Team-Berechtigungen. Wenn nur Lese-Zugriff vergeben wurde, werden Schreib-Endpoints mit HTTP 403 abgelehnt.

Gibt es Rate Limits?

Ja, zum Schutz der Plattform existieren Rate Limits. Bei produktiver Last (Bulk-Operationen, Initial-Migration) sprechen Sie uns vorab an — wir passen die Limits ggf. an.

Kann ich die API zum initialen Bestandsimport nutzen?

Ja — für strukturierte Migrationen ist die API der bevorzugte Weg. Für sehr große Bestände (>10.000 Verträge) empfehlen wir eine kurze Abstimmung mit unserem Team, damit Rate Limits und Datentypen optimal vorbereitet sind.

Wie informiert mich ContractHero über API-Änderungen?

Wir bemühen uns, Breaking Changes mit angemessener Vorlaufzeit zu kommunizieren. Hinterlassen Sie beim Setup einen Kontakt für API-Mitteilungen.

Wie verhalten sich REST API und Webhooks zueinander?

Sie ergänzen sich: Die REST API ist pull-basiert (Sie holen Daten oder lösen Aktionen aus). Webhooks sind push-basiert (ContractHero meldet sich, wenn etwas passiert). Viele Integrationen nutzen beides — Webhooks für die Trigger, API für die Folgeaktion.

Und wenn ich gar nicht programmieren will?

Für Abfragen aus einem KI-Assistenten heraus gibt es die MCP-Schnittstelle — technisch dieselbe API, nur so verpackt, dass Claude oder ChatGPT sie direkt nutzen können. Ohne Entwicklungsaufwand, dafür rein lesend.

Gut zu wissen

OpenAPI-Spec direkt in Postman laden. Über „Download OpenAPI Document" in der Live-Doku erhalten Sie eine maschinenlesbare Spec. In Postman/Insomnia importieren — und Sie haben sofort alle Endpoints mit Beispiel-Bodies bereit.
Testen Sie zuerst lesend. Bevor Sie produktiv Verträge anlegen, prüfen Sie mit GET-Endpoints, ob Zugang, Organisations-ID und Team-ID stimmen. Spart Aufräumarbeit, wenn etwas schiefläuft.
Idempotenz endpoint-seitig sicherstellen. Wenn Ihre Integration einen Vertrag zweimal POST'et (z. B. nach einem Retry), entsteht ein Duplikat. Speichern Sie Quelle-IDs und prüfen Sie vor jedem Create.
API + Webhooks ist die volle Power. Webhooks triggern Ihren Workflow, die API holt anschließend die kompletten Daten und führt die Folgeaktion aus. Wer beide kombiniert, baut robuste, fast-realtime Integrationen.
Wir unterstützen beim Setup. Wenn Sie unsicher beim Endpoint-Design oder bei Migrationen sind, vereinbaren Sie einen Discovery-Call mit dem ContractHero-Team — eine Stunde spart oft Wochen.

Kontakt

Bei Fragen, Zugangs-Anfragen oder Migrations-Begleitung erreichen Sie uns über den ContractHero-Webchat oder per E-Mail an support@contracthero.com.