API-Dokumentation

Vollständige REST-API-Referenz für staffSign – Verträge erstellen, versenden und signieren.

Version 1.0 · Stand 2026-03-31

Basis-URL

https://api.promotionbasis.de/staffsign

Endpunkt-Übersicht

Method	Pfad	Beschreibung
POST	/staffsign/contracts	Vertrag erstellen
GET	/staffsign/contracts	Verträge auflisten
GET	/staffsign/contracts/{id}	Vertrag abrufen
POST	/staffsign/contracts/{id}/send	Vertrag versenden
POST	/staffsign/contracts/{id}/cancel	Vertrag stornieren
DELETE	/staffsign/contracts/{id}	Vertrag löschen
POST	/staffsign/contracts/preview	Vertragsvorschau
GET	/staffsign/contracts/{id}/download/signed	Signiertes PDF herunterladen
GET	/staffsign/contracts/{id}/download/audit-trail	Audit-Trail herunterladen
GET	/staffsign/contracts/{id}/download/sealed	Versiegeltes PDF herunterladen
POST	/staffsign/contracts/{id}/deliver	Zustellung auslösen
POST	/staffsign/contract_templates	Template erstellen
GET	/staffsign/contract_templates	Templates auflisten
GET	/staffsign/contract_templates/{id}	Template abrufen
PATCH	/staffsign/contract_templates/{id}	Template aktualisieren
POST	/staffsign/contract_templates/{id}/activate	Template aktivieren
DELETE	/staffsign/contract_templates/{id}	Template archivieren
POST	/staffsign/contract_templates/validate	Template validieren

1. Authentifizierung

1.1 API-Key erstellen

API-Keys werden über das iPM-Dashboard verwaltet:

In iPM einloggen unter pm.promotionbasis.de
Navigieren Sie zu staffSign > API-Zugang
Klicken Sie auf API-Key erstellen
Optional: Vergeben Sie einen Titel (z. B. „Production“, „Staging“)
Der vollständige API-Key wird einmalig angezeigt — sicher speichern

Wichtig: Der API-Key kann nach der Erstellung nicht erneut angezeigt werden. Bei Verlust muss ein neuer Key generiert werden.

1.2 API-Key verwenden

Alle Requests müssen den API-Key im X-Api-Key-Header enthalten:

HTTP-Request

GET /staffsign/contracts
X-Api-Key: <api-key>
Accept: application/json

1.3 Key-Format

Format: {userId}.{randomPart} — UUID-Präfix + 32-Zeichen-Zufallsteil:

550e8400-e29b-41d4-a716-446655440000.aB3dE7fG9hJ2kL5mN8pQ1rS4tU6vW0xY

1.4 Datenisolation & Key-Verwaltung

Jeder API-Key ist an eine Organization gebunden. Alle Daten sind automatisch auf die eigene Organization beschränkt.

Aktion	Beschreibung
Erstellen	Neuen Key generieren. Mehrere Keys pro Organization möglich
Regenerieren	Neuen Key für bestehenden Eintrag. Alter Key wird sofort ungültig
Deaktivieren	Key temporär sperren (kann reaktiviert werden)
Aktivieren	Gesperrten Key wieder aktivieren
Löschen	Key permanent entfernen

2. Allgemeine Konventionen

2.1 Content-Type & Accept

Requests: Content-Type: application/json. Mit Accept: application/json erhalten Sie schlankes JSON ohne Hydra-Metadaten. Ohne diesen Header liefern Listen-Endpunkte application/ld+json zurück.

2.2 HTTP-Statuscodes

Code	Bedeutung
200	Erfolg (mit Response-Body)
201	Ressource erstellt (mit Response-Body)
204	Erfolg ohne Response-Body (Cancel, Delete, Activate, Update, Validate)
401	Ungültiger oder fehlender API-Key
403	Keine Berechtigung für diese Ressource
404	Ressource nicht gefunden
422	Validierungsfehler
500	Interner Serverfehler

2.3 Datumsformate

Kontext	Format	Beispiel
Datumseingabe (Request)	YYYY-MM-DD	2026-04-01
Zeiteingabe (Request)	HH:MM	09:00
Datum in Response	YYYY-MM-DD	2026-04-01
Zeitstempel in Response	YYYY-MM-DD HH:MM:SS	2026-03-31 14:30:00
Zeitstempel (signedAt, Webhook)	ISO 8601	2026-03-31T14:30:00+00:00

2.4 Enum-Werte

Format: kategorie.wert. In Responses doppelt: fieldName (lesbarer Text) und fieldNameKey (maschinenlesbarer Wert). Für Requests immer den Key-Wert verwenden.

2.5 Pagination

Parameter	Beschreibung	Default	Max
page	Seitennummer	1	—
itemsPerPage	Einträge pro Seite	30	100

Mit Accept: application/ld+json enthält die Response Hydra-Metadaten mit hydra:totalItems für Pagination-Metadaten.

3. Endpunkte: Contracts

POST/staffsign/contractsVertrag erstellen

Erstellt einen neuen Vertrag auf Basis einer Vorlage. Mindestens 2 Teilnehmer mit unterschiedlichen Rollen erforderlich.

Request Body

{
  "contractTemplateId": "550e8400-e29b-41d4-a716-446655440000",
  "signatureLevel": "signature_level.qes",
  "contractType": "contract_type.employment",
  "participants": [
    {
      "role": "contract_participant_role.employer",
      "signingMethod": "signing_method.digital",
      "participantId": null,
      "participantData": {
        "email": "hr@acme-staffing.de",
        "firstName": "Anna",
        "lastName": "Schmidt",
        "company": "ACME Staffing GmbH",
        "gender": "gender.female",
        "street": "Musterstrasse 123",
        "zipcode": "10115",
        "city": "Berlin",
        "country": "country.de"
      }
    },
    {
      "role": "contract_participant_role.employee",
      "signingMethod": "signing_method.digital",
      "participantData": {
        "email": "max.mustermann@example.com",
        "firstName": "Max",
        "lastName": "Mustermann",
        "dateOfBirth": "1990-05-15"
      }
    }
  ],
  "terms": {
    "startDate": "2026-04-01",
    "endDate": "2026-09-30",
    "compensationType": "compensation_type.hourly",
    "compensationAmount": 18.50,
    "compensationDescription": "Stundenlohn zzgl. Zuschlaege",
    "location": "Berlin, verschiedene Einsatzorte"
  },
  "employment": {
    "employmentType": "employment_type.temporary",
    "workDescription": "Promotion- und Messeeinsaetze",
    "probationPeriod": "6 Monate",
    "cancellationPeriod": "2 Wochen zum Monatsende"
  },
  "workingTime": {
    "scheduleType": "schedule_type.flexible",
    "description": "Ca. 20-40 Stunden pro Woche",
    "dailySchedule": [
      {
        "date": "2026-04-01",
        "startTime": "09:00",
        "endTime": "17:00",
        "breakMinutes": 30
      }
    ]
  },
  "usePbCoinContingent": false,
  "sendImmediately": false,
  "autoDeliverSignedDocument": true
}

Top-Level-Felder

Feld	Typ	Pflicht	Beschreibung
contractTemplateId	UUID	Ja	ID der zu verwendenden Vertragsvorlage
signatureLevel	string	Ja	Signatur-Stufe (→ Enum 9.1)
contractType	string	Nein	Vertragstyp, Default: contract_type.employment
participants	array	Ja	Mindestens 2 Teilnehmer (siehe participants[])
terms	object	Ja	Vertragsbedingungen (siehe terms)
employment	object	Nein	Beschäftigungsdetails (siehe employment)
workingTime	object	Nein	Arbeitszeitregelung (siehe workingTime)
additionalTerms	object	Nein	Zusätzliche Felder (freie Struktur)
usePbCoinContingent	boolean	Nein	pbCoins für Signaturkosten verwenden (Default: false)
sendImmediately	boolean	Nein	Vertrag sofort versenden (Default: true)
autoDeliverSignedDocument	boolean	Nein	Signiertes Dokument automatisch per E-Mail zustellen, sobald alle signiert haben (Default: true). Bei false muss die Zustellung manuell über POST /deliver ausgelöst werden.

participants[] — Teilnehmer

Feld	Typ	Pflicht	Beschreibung
role	string	Ja	Teilnehmerrolle (→ Enum 9.3)
signingMethod	string	Ja	Signaturmethode (→ Enum 9.2)
participantId	string	Nein	Optionale externe Referenz-ID
participantData	object	Ja	Teilnehmerdaten (→ Abschnitt 8.3)

terms — Vertragsbedingungen

Feld	Typ	Pflicht	Beschreibung
startDate	string	Ja	Vertragsbeginn (YYYY-MM-DD)
endDate	string	Nein	Vertragsende (YYYY-MM-DD)
compensationType	string	Ja	Vergütungsart (→ Enum 9.5)
compensationAmount	number	Ja	Vergütungsbetrag (>= 0)
compensationDescription	string	Nein	Beschreibung der Vergütung (max. 500 Zeichen)
location	string	Nein	Arbeitsort (max. 500 Zeichen)

employment — Beschäftigungsdetails (optional)

Feld	Typ	Pflicht	Beschreibung
employmentType	string	Ja*	Beschäftigungsart (→ Enum 9.6)
workDescription	string	Nein	Tätigkeitsbeschreibung (max. 2000 Zeichen)
probationPeriod	string	Nein	Probezeit (max. 255 Zeichen)
cancellationPeriod	string	Nein	Kündigungsfrist (max. 255 Zeichen)

* Pflicht wenn das employment-Objekt mitgesendet wird.

workingTime — Arbeitszeitregelung (optional)

Feld	Typ	Pflicht	Beschreibung
scheduleType	string	Ja*	Arbeitszeitmodell (→ Enum 9.7)
description	string	Ja*	Beschreibung der Arbeitszeit (max. 2000 Zeichen)
dailySchedule	array	Nein	Tagesplan-Einträge (siehe dailySchedule[])

dailySchedule[] — Tagesplan-Einträge

Feld	Typ	Pflicht	Beschreibung
date	string	Ja	Datum (YYYY-MM-DD)
startTime	string	Ja	Startzeit (HH:MM)
endTime	string	Ja	Endzeit (HH:MM)
breakMinutes	integer	Nein	Pausendauer in Minuten (>= 0)

sendImmediately: true (Default): Direkt versendet. Status: contract_status.sent

sendImmediately: false: Als Draft erstellt. Separat über POST /contracts/{id}/send versenden.

Response: 201 Created — vollständige Contract-Struktur. E-Mail-Adressen müssen über alle Teilnehmer eindeutig sein.

Response 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "org-uuid",
  "jobPostingId": null,
  "contractTemplateId": "template-uuid",
  "contractTemplateName": "Arbeitsvertrag Standard",
  "contractType": "Arbeitsvertrag",
  "contractTypeKey": "contract_type.employment",
  "status": "Entwurf",
  "statusKey": "contract_status.draft",
  "signatureLevel": "Qualifizierte elektronische Signatur",
  "signatureLevelKey": "signature_level.qes",
  "participants": [
    {
      "id": "participant-uuid-1",
      "role": "Arbeitgeber",
      "roleKey": "contract_participant_role.employer",
      "signingMethod": "Digitale Signatur",
      "signingMethodKey": "signing_method.digital",
      "participantId": null,
      "participantData": {
        "email": "hr@acme-staffing.de",
        "firstName": "Anna",
        "lastName": "Schmidt",
        "dateOfBirth": null,
        "company": "ACME Staffing GmbH",
        "gender": "gender.female",
        "phone": "+49 30 123456",
        "street": "Musterstrasse 123",
        "zipcode": "10115",
        "city": "Berlin",
        "country": "country.de"
      },
      "signedAt": null,
      "qesVerifiedAt": null
    }
  ],
  "startDate": "2026-04-01",
  "endDate": "2026-09-30",
  "compensationType": "Stuendlich",
  "compensationTypeKey": "compensation_type.hourly",
  "compensationAmount": "18.5",
  "sentAt": null,
  "createdAt": "2026-03-31 14:30:00",
  "autoDeliverSignedDocument": true,
  "signedDocumentDeliveredAt": null,
  // Nur beim Einzelabruf (GET /contracts/{id}):
  "expiresAt": null,
  "renderedContent": "<h1>Arbeitsvertrag</h1>...",
  "compensationDescription": "Stundenlohn zzgl. Zuschlaege",
  "location": "Berlin, verschiedene Einsatzorte",
  "employmentType": "Befristet",
  "employmentTypeKey": "employment_type.temporary",
  "workDescription": "Promotion- und Messeeinsaetze",
  "probationPeriod": "6 Monate",
  "cancellationPeriod": "2 Wochen zum Monatsende",
  "scheduleType": "Flexibel",
  "scheduleTypeKey": "schedule_type.flexible",
  "workingTimeDescription": "Ca. 20-40 Stunden pro Woche",
  "externalDocumentId": null,
  "signedDocumentUrl": null,
  "auditTrailPdfUrl": null,
  "sealedPdfUrl": null
}

GET/staffsign/contractsVerträge auflisten

Listet alle Verträge der Organization auf. Unterstützt Pagination via ?page= und ?itemsPerPage=.

Request Body: Kein Body erforderlich.

Response 200 OK — Array

[
  {
    "id": "contract-uuid-1",
    "organizationId": "org-uuid",
    "jobPostingId": null,
    "contractTemplateId": "template-uuid",
    "contractTemplateName": "Arbeitsvertrag Standard",
    "contractType": "Arbeitsvertrag",
    "contractTypeKey": "contract_type.employment",
    "status": "Versendet",
    "statusKey": "contract_status.sent",
    "signatureLevel": "Qualifizierte elektronische Signatur",
    "signatureLevelKey": "signature_level.qes",
    "participants": [
      {
        "id": "participant-uuid-1",
        "role": "Arbeitgeber",
        "roleKey": "contract_participant_role.employer",
        "signingMethod": "Digitale Signatur",
        "signingMethodKey": "signing_method.digital",
        "participantId": null,
        "participantData": {
          "email": "hr@acme-staffing.de",
          "firstName": "Anna",
          "lastName": "Schmidt",
          "dateOfBirth": null,
          "company": "ACME Staffing GmbH",
          "gender": "gender.female",
          "phone": "+49 30 123456",
          "street": "Musterstrasse 123",
          "zipcode": "10115",
          "city": "Berlin",
          "country": "country.de"
        },
        "signedAt": null,
        "qesVerifiedAt": null
      }
    ],
    "startDate": "2026-04-01",
    "endDate": "2026-09-30",
    "compensationType": "Stuendlich",
    "compensationTypeKey": "compensation_type.hourly",
    "compensationAmount": "18.5",
    "sentAt": "2026-03-31 14:35:00",
    "createdAt": "2026-03-31 14:30:00",
    "autoDeliverSignedDocument": true
  }
]

Listenansicht vs. Einzelabruf: Folgende Felder sind nur beim Einzelabruf (GET /contracts/{id}) verfügbar:renderedContent, compensationDescription, location, employmentType/Key, workDescription, probationPeriod, cancellationPeriod, scheduleType/Key, workingTimeDescription, externalDocumentId, signedDocumentUrl, auditTrailPdfUrl, sealedPdfUrl, expiresAt, signedDocumentDeliveredAt.

GET/staffsign/contracts/{id}Vertrag abrufen

Gibt die vollständige Contract-Struktur zurück — inkl. renderedContent, signedDocumentUrl und aller Detail-Felder (nur beim Einzelabruf verfügbar).

Request Body: Kein Body erforderlich.

Response 200 OK — vollständige Contract-Struktur

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "org-uuid",
  "jobPostingId": null,
  "contractTemplateId": "template-uuid",
  "contractTemplateName": "Arbeitsvertrag Standard",
  "contractType": "Arbeitsvertrag",
  "contractTypeKey": "contract_type.employment",
  "status": "Entwurf",
  "statusKey": "contract_status.draft",
  "signatureLevel": "Qualifizierte elektronische Signatur",
  "signatureLevelKey": "signature_level.qes",
  "participants": [
    {
      "id": "participant-uuid-1",
      "role": "Arbeitgeber",
      "roleKey": "contract_participant_role.employer",
      "signingMethod": "Digitale Signatur",
      "signingMethodKey": "signing_method.digital",
      "participantId": null,
      "participantData": {
        "email": "hr@acme-staffing.de",
        "firstName": "Anna",
        "lastName": "Schmidt",
        "dateOfBirth": null,
        "company": "ACME Staffing GmbH",
        "gender": "gender.female",
        "phone": "+49 30 123456",
        "street": "Musterstrasse 123",
        "zipcode": "10115",
        "city": "Berlin",
        "country": "country.de"
      },
      "signedAt": null,
      "qesVerifiedAt": null
    }
  ],
  "startDate": "2026-04-01",
  "endDate": "2026-09-30",
  "compensationType": "Stuendlich",
  "compensationTypeKey": "compensation_type.hourly",
  "compensationAmount": "18.5",
  "sentAt": null,
  "createdAt": "2026-03-31 14:30:00",
  "autoDeliverSignedDocument": true,
  "signedDocumentDeliveredAt": null,
  // Nur beim Einzelabruf (GET /contracts/{id}):
  "expiresAt": null,
  "renderedContent": "<h1>Arbeitsvertrag</h1>...",
  "compensationDescription": "Stundenlohn zzgl. Zuschlaege",
  "location": "Berlin, verschiedene Einsatzorte",
  "employmentType": "Befristet",
  "employmentTypeKey": "employment_type.temporary",
  "workDescription": "Promotion- und Messeeinsaetze",
  "probationPeriod": "6 Monate",
  "cancellationPeriod": "2 Wochen zum Monatsende",
  "scheduleType": "Flexibel",
  "scheduleTypeKey": "schedule_type.flexible",
  "workingTimeDescription": "Ca. 20-40 Stunden pro Woche",
  "externalDocumentId": null,
  "signedDocumentUrl": null,
  "auditTrailPdfUrl": null,
  "sealedPdfUrl": null
}

POST/staffsign/contracts/{id}/sendVertrag versenden

Sendet einen Draft-Vertrag zur Signatur an alle Teilnehmer mit signing_method.digital.

Request Body

// // Kein Request-Body erforderlich — kein Response-Body

Response 200 OK — Contract-Struktur mit statusKey: contract_status.sent

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "org-uuid",
  "jobPostingId": null,
  "contractTemplateId": "template-uuid",
  "contractTemplateName": "Arbeitsvertrag Standard",
  "contractType": "Arbeitsvertrag",
  "contractTypeKey": "contract_type.employment",
  "status": "Entwurf",
  "statusKey": "contract_status.draft",
  "signatureLevel": "Qualifizierte elektronische Signatur",
  "signatureLevelKey": "signature_level.qes",
  "participants": [
    {
      "id": "participant-uuid-1",
      "role": "Arbeitgeber",
      "roleKey": "contract_participant_role.employer",
      "signingMethod": "Digitale Signatur",
      "signingMethodKey": "signing_method.digital",
      "participantId": null,
      "participantData": {
        "email": "hr@acme-staffing.de",
        "firstName": "Anna",
        "lastName": "Schmidt",
        "dateOfBirth": null,
        "company": "ACME Staffing GmbH",
        "gender": "gender.female",
        "phone": "+49 30 123456",
        "street": "Musterstrasse 123",
        "zipcode": "10115",
        "city": "Berlin",
        "country": "country.de"
      },
      "signedAt": null,
      "qesVerifiedAt": null
    }
  ],
  "startDate": "2026-04-01",
  "endDate": "2026-09-30",
  "compensationType": "Stuendlich",
  "compensationTypeKey": "compensation_type.hourly",
  "compensationAmount": "18.5",
  "sentAt": null,
  "createdAt": "2026-03-31 14:30:00",
  "autoDeliverSignedDocument": true,
  "signedDocumentDeliveredAt": null,
  // Nur beim Einzelabruf (GET /contracts/{id}):
  "expiresAt": null,
  "renderedContent": "<h1>Arbeitsvertrag</h1>...",
  "compensationDescription": "Stundenlohn zzgl. Zuschlaege",
  "location": "Berlin, verschiedene Einsatzorte",
  "employmentType": "Befristet",
  "employmentTypeKey": "employment_type.temporary",
  "workDescription": "Promotion- und Messeeinsaetze",
  "probationPeriod": "6 Monate",
  "cancellationPeriod": "2 Wochen zum Monatsende",
  "scheduleType": "Flexibel",
  "scheduleTypeKey": "schedule_type.flexible",
  "workingTimeDescription": "Ca. 20-40 Stunden pro Woche",
  "externalDocumentId": null,
  "signedDocumentUrl": null,
  "auditTrailPdfUrl": null,
  "sealedPdfUrl": null
}

Voraussetzung: Vertrag muss Status contract_status.draft haben.

POST/staffsign/contracts/{id}/cancelVertrag stornieren

Storniert einen versendeten Vertrag. Auch Verträge mit Teilunterschriften können storniert werden.

Request Body

// // Kein Request-Body erforderlich — kein Response-Body

Response

// 204 No Content — kein Response-Body

Voraussetzung: Status contract_status.sent.
Kosten bei Teilunterschriften: Wenn mindestens ein Teilnehmer bereits signiert hat, werden volle Signaturkosten berechnet.

DELETE/staffsign/contracts/{id}Vertrag löschen

Löscht einen Draft-Vertrag permanent. Versendete oder signierte Verträge können nicht gelöscht, aber storniert werden.

Request Body

// // Kein Request-Body erforderlich — kein Response-Body

Response

// 204 No Content — kein Response-Body

Voraussetzung: Vertrag muss Status contract_status.draft haben.

POST/staffsign/contracts/previewVertragsvorschau

Rendert eine Vorschau ohne Datenspeicherung. Ideal zum Testen von Template und Daten. Kein Datensatz wird erstellt.

Request Body: Identisch zum POST /contracts-Request.

Request Body (identisch zu POST /contracts)

{
  "contractTemplateId": "550e8400-e29b-41d4-a716-446655440000",
  "signatureLevel": "signature_level.qes",
  "contractType": "contract_type.employment",
  "participants": [
    {
      "role": "contract_participant_role.employer",
      "signingMethod": "signing_method.digital",
      "participantId": null,
      "participantData": {
        "email": "hr@acme-staffing.de",
        "firstName": "Anna",
        "lastName": "Schmidt",
        "company": "ACME Staffing GmbH",
        "gender": "gender.female",
        "street": "Musterstrasse 123",
        "zipcode": "10115",
        "city": "Berlin",
        "country": "country.de"
      }
    },
    {
      "role": "contract_participant_role.employee",
      "signingMethod": "signing_method.digital",
      "participantData": {
        "email": "max.mustermann@example.com",
        "firstName": "Max",
        "lastName": "Mustermann",
        "dateOfBirth": "1990-05-15"
      }
    }
  ],
  "terms": {
    "startDate": "2026-04-01",
    "endDate": "2026-09-30",
    "compensationType": "compensation_type.hourly",
    "compensationAmount": 18.50,
    "compensationDescription": "Stundenlohn zzgl. Zuschlaege",
    "location": "Berlin, verschiedene Einsatzorte"
  },
  "employment": {
    "employmentType": "employment_type.temporary",
    "workDescription": "Promotion- und Messeeinsaetze",
    "probationPeriod": "6 Monate",
    "cancellationPeriod": "2 Wochen zum Monatsende"
  },
  "workingTime": {
    "scheduleType": "schedule_type.flexible",
    "description": "Ca. 20-40 Stunden pro Woche",
    "dailySchedule": [
      {
        "date": "2026-04-01",
        "startTime": "09:00",
        "endTime": "17:00",
        "breakMinutes": 30
      }
    ]
  },
  "usePbCoinContingent": false,
  "sendImmediately": false,
  "autoDeliverSignedDocument": true
}

Response 200 OK

{
  "contract": {
    "id": "preview-uuid-nicht-persistiert",
    "organizationId": "org-uuid",
    "jobPostingId": null,
    "contractTemplateId": "template-uuid",
    "contractTemplateName": "Arbeitsvertrag Standard",
    "contractType": "Arbeitsvertrag",
    "contractTypeKey": "contract_type.employment",
    "status": "Entwurf",
    "statusKey": "contract_status.draft",
    "signatureLevel": "Qualifizierte elektronische Signatur",
    "signatureLevelKey": "signature_level.qes",
    "participants": [
      {
        "id": "preview-participant-uuid-1",
        "role": "Arbeitgeber",
        "roleKey": "contract_participant_role.employer",
        "signingMethod": "Digitale Signatur",
        "signingMethodKey": "signing_method.digital",
        "participantId": null,
        "participantData": {
          "email": "hr@acme-staffing.de",
          "firstName": "Anna",
          "lastName": "Schmidt",
          "dateOfBirth": null,
          "company": "ACME Staffing GmbH",
          "gender": "gender.female",
          "phone": "+49 30 123456",
          "street": "Musterstrasse 123",
          "zipcode": "10115",
          "city": "Berlin",
          "country": "country.de"
        },
        "signedAt": null,
        "qesVerifiedAt": null
      },
      {
        "id": "preview-participant-uuid-2",
        "role": "Arbeitnehmer",
        "roleKey": "contract_participant_role.employee",
        "signingMethod": "Digitale Signatur",
        "signingMethodKey": "signing_method.digital",
        "participantId": null,
        "participantData": {
          "email": "max.mustermann@example.com",
          "firstName": "Max",
          "lastName": "Mustermann",
          "dateOfBirth": "1990-05-15 00:00:00",
          "company": null,
          "gender": null,
          "phone": null,
          "street": "Beispielweg 42",
          "zipcode": "10178",
          "city": "Berlin",
          "country": "country.de"
        },
        "signedAt": null,
        "qesVerifiedAt": null
      }
    ],
    "startDate": "2026-04-01",
    "endDate": "2026-09-30",
    "compensationType": "Stuendlich",
    "compensationTypeKey": "compensation_type.hourly",
    "compensationAmount": "18.5",
    "compensationDescription": "Stundenlohn zzgl. Zuschlaege",
    "location": "Berlin, verschiedene Einsatzorte",
    "employmentType": "Befristet",
    "employmentTypeKey": "employment_type.temporary",
    "workDescription": "Promotion- und Messeeinsaetze",
    "probationPeriod": "6 Monate",
    "cancellationPeriod": "2 Wochen zum Monatsende",
    "scheduleType": "Flexibel",
    "scheduleTypeKey": "schedule_type.flexible",
    "workingTimeDescription": "Ca. 20-40 Stunden pro Woche",
    "renderedContent": "<h1>Arbeitsvertrag</h1><p>Zwischen ACME Staffing GmbH...</p>",
    "externalDocumentId": null,
    "signedDocumentUrl": null,
    "auditTrailPdfUrl": null,
    "sealedPdfUrl": null,
    "expiresAt": null,
    "sentAt": null,
    "createdAt": "2026-04-01 10:00:00"
  },
  "renderedContent": "<h1>Arbeitsvertrag</h1><p>Zwischen ACME Staffing GmbH...</p>",
  "canBeSent": true,
  "missingPlaceholders": [],
  "articles": [
    {
      "articleNumber": "20.20.20.00",
      "productType": "product_type.signature",
      "productCategory": "product_category.staffsign",
      "title": "QES-Signatur",
      "description": "Qualifizierte elektronische Signatur",
      "quantity": 2,
      "unitPrice": 6.0,
      "sumPrice": 12.0,
      "listUnitPrice": 6.0,
      "listSumPrice": 12.0,
      "discountInfo": null,
      "pbCoinPrice": 300,
      "pbCoinGain": 0,
      "pbCoinDiscount": 0
    }
  ],
  "requiresIdentification": true,
  "requiresOrganizationIdentification": false
}

Response-Felder

Feld	Typ	Beschreibung
contract	object	Vollständige Contract-Struktur (Vorschau, nicht gespeichert)
renderedContent	string	Gerenderter HTML-Inhalt des Vertrags
canBeSent	boolean	true wenn alle Platzhalter befüllt sind
missingPlaceholders	array	Liste fehlender Platzhalter-Namen
articles	array	Berechnete Kostenartikel (Signaturprodukte mit Preis + pbCoin-Wert)
requiresIdentification	boolean	QES-Identifikation für Empfänger erforderlich
requiresOrganizationIdentification	boolean	QES-Identifikation für Organization erforderlich

GET/staffsign/contracts/{id}/download/signedSigniertes PDF herunterladen

Lädt das signierte Vertrags-PDF als Datei herunter. Verfügbar, sobald alle Teilnehmer signiert haben (statusKey: contract_status.signed) und signedDocumentUrl gesetzt ist.

Request Body: Kein Body erforderlich.

Response: 200 OK – Content-Type: application/pdf, Dateiname contract_{id}_signed.pdf.

Voraussetzung: Vertrag muss vollständig signiert sein und signedDocumentUrl gesetzt haben.

GET/staffsign/contracts/{id}/download/audit-trailAudit-Trail-PDF herunterladen

Lädt den Audit-Trail als PDF herunter. Er enthält ein kryptographisch verifizierbares Protokoll aller Signaturereignisse (wer, wann, IP-Adresse, Verifizierungsmethode). Verfügbar nach vollständiger Signierung (auditTrailPdfUrl gesetzt).

Request Body: Kein Body erforderlich.

Response: 200 OK – Content-Type: application/pdf, Dateiname contract_{id}_audit_trail.pdf.

GET/staffsign/contracts/{id}/download/sealedVersiegeltes PDF herunterladen

Lädt das versiegelte PDF mit eingebetteten digitalen Signaturen und angehängtem Audit-Trail herunter. Es ist das langzeitarchivierungsfähige Endprodukt des Signaturprozesses (sealedPdfUrl gesetzt).

Request Body: Kein Body erforderlich.

Response: 200 OK – Content-Type: application/pdf, Dateiname contract_{id}_sealed.pdf.

POST/staffsign/contracts/{id}/deliverZustellung manuell auslösen

Löst die Zustellung des signierten Dokuments per E-Mail an alle Teilnehmer aus. Nur nötig, wenn der Vertrag mit autoDeliverSignedDocument: false erstellt wurde. Bei automatischer Zustellung (Standard) wird dieser Endpunkt nicht gebraucht.

Request Body: Kein Body erforderlich.

Response 200 OK – aktualisierter Vertrag (signedDocumentDeliveredAt gesetzt)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "org-uuid",
  "jobPostingId": null,
  "contractTemplateId": "template-uuid",
  "contractTemplateName": "Arbeitsvertrag Standard",
  "contractType": "Arbeitsvertrag",
  "contractTypeKey": "contract_type.employment",
  "status": "Entwurf",
  "statusKey": "contract_status.draft",
  "signatureLevel": "Qualifizierte elektronische Signatur",
  "signatureLevelKey": "signature_level.qes",
  "participants": [
    {
      "id": "participant-uuid-1",
      "role": "Arbeitgeber",
      "roleKey": "contract_participant_role.employer",
      "signingMethod": "Digitale Signatur",
      "signingMethodKey": "signing_method.digital",
      "participantId": null,
      "participantData": {
        "email": "hr@acme-staffing.de",
        "firstName": "Anna",
        "lastName": "Schmidt",
        "dateOfBirth": null,
        "company": "ACME Staffing GmbH",
        "gender": "gender.female",
        "phone": "+49 30 123456",
        "street": "Musterstrasse 123",
        "zipcode": "10115",
        "city": "Berlin",
        "country": "country.de"
      },
      "signedAt": null,
      "qesVerifiedAt": null
    }
  ],
  "startDate": "2026-04-01",
  "endDate": "2026-09-30",
  "compensationType": "Stuendlich",
  "compensationTypeKey": "compensation_type.hourly",
  "compensationAmount": "18.5",
  "sentAt": null,
  "createdAt": "2026-03-31 14:30:00",
  "autoDeliverSignedDocument": true,
  "signedDocumentDeliveredAt": null,
  // Nur beim Einzelabruf (GET /contracts/{id}):
  "expiresAt": null,
  "renderedContent": "<h1>Arbeitsvertrag</h1>...",
  "compensationDescription": "Stundenlohn zzgl. Zuschlaege",
  "location": "Berlin, verschiedene Einsatzorte",
  "employmentType": "Befristet",
  "employmentTypeKey": "employment_type.temporary",
  "workDescription": "Promotion- und Messeeinsaetze",
  "probationPeriod": "6 Monate",
  "cancellationPeriod": "2 Wochen zum Monatsende",
  "scheduleType": "Flexibel",
  "scheduleTypeKey": "schedule_type.flexible",
  "workingTimeDescription": "Ca. 20-40 Stunden pro Woche",
  "externalDocumentId": null,
  "signedDocumentUrl": null,
  "auditTrailPdfUrl": null,
  "sealedPdfUrl": null
}

Voraussetzung: Vertrag muss vollständig signiert sein. Ist bereits zugestellt (signedDocumentDeliveredAt gesetzt), gibt die API einen Fehler zurück.

4. Endpunkte: Contract Templates

POST/staffsign/contract_templatesTemplate erstellen

Erstellt eine neue Vertragsvorlage. Neues Template hat Status contract_template_status.draft und muss separat aktiviert werden.

Request Body

{
  "name": "Arbeitsvertrag Befristet",
  "description": "Vorlage fuer befristete Arbeitsvertraege im Promotionbereich",
  "content": "# Arbeitsvertrag\n\nZwischen **{{ employer.company }}**, vertreten durch {{ employer.fullName }},\nnachfolgend \"Arbeitgeber\",\n\nund **{{ employee.fullName }}**, geb. am {{ employee.dateOfBirth }},\nnachfolgend \"Arbeitnehmer\".\n\n## § 1 Beginn und Dauer\n\nDas Arbeitsverhaeltnis beginnt am {{ contract.startDate }}.",
  "renderLogo": true
}

Request-Felder

Feld	Typ	Pflicht	Beschreibung
name	string	Ja	Name der Vorlage (2–255 Zeichen)
description	string	Nein	Beschreibung (max. 1000 Zeichen)
content	string	Ja	Template-Inhalt in Markdown + Twig-Syntax (min. 10 Zeichen)
renderLogo	boolean	Nein	Organisations-Logo im PDF-Header rendern (Default: true)

Template-Syntax (Markdown + Twig)

content — Beispiel

# Arbeitsvertrag

Zwischen **{{ employer.company }}**, vertreten durch {{ employer.fullName }},
nachfolgend "Arbeitgeber",

und **{{ employee.fullName }}**, geb. am {{ employee.dateOfBirth }},
nachfolgend "Arbeitnehmer".

## § 1 Beginn und Dauer

Das Arbeitsverhaeltnis beginnt am {{ contract.startDate }}
und ist befristet bis {{ contract.endDate }}.

## § 2 Verguetung

Verguetung: {{ contract.compensationAmount }} EUR ({{ contract.compensationType }}).

Ort, Datum: {{ today }}

Verfügbare Platzhalter-Gruppen

Prefix	Beschreibung	Beispiele
employer.*	Arbeitgeber-Daten	employer.company, employer.fullName, employer.email
employee.*	Arbeitnehmer-Daten	employee.fullName, employee.dateOfBirth, employee.street
contract.*	Vertragsbedingungen	contract.startDate, contract.endDate, contract.compensationAmount
employment.*	Beschäftigungsdetails	employment.type, employment.workDescription
workingTime.*	Arbeitszeitdaten	workingTime.scheduleType, workingTime.description
today	Aktuelles Datum	today

Unbekannte Platzhalter werden bei der Validierung als Fehler zurückgegeben (422).

Response 201 Created

{
  "id": "template-uuid",
  "name": "Arbeitsvertrag Standard",
  "description": "Standard-Arbeitsvertrag fuer befristete Beschaeftigung",
  "content": "# Arbeitsvertrag\n\nZwischen **{{ employer.company }}**, vertreten durch {{ employer.fullName }}...",
  "renderLogo": true,
  "isSystemTemplate": false,
  "organizationId": "org-uuid",
  "status": "Aktiv",
  "statusKey": "contract_template_status.active",
  "createdAt": "2026-03-01 10:00:00",
  "lastModified": "2026-03-15 14:30:00",
  "usedPlaceholders": [
    "employer.company",
    "employer.fullName",
    "employee.fullName",
    "employee.dateOfBirth",
    "contract.startDate",
    "contract.compensationAmount"
  ],
  "requiredFields": [
    "contract.compensationAmount",
    "contract.startDate",
    "employee.dateOfBirth",
    "employee.firstName",
    "employee.lastName",
    "employer.company",
    "employer.firstName",
    "employer.lastName"
  ]
}

GET/staffsign/contract_templatesTemplates auflisten

Listet alle verfügbaren Templates auf. Unterstützt Pagination via ?page= und ?itemsPerPage=.

Request Body: Kein Body erforderlich.

Response 200 OK — Array (vollständige Struktur, kein reduzierter Listen-Modus)

[
  {
    "id": "template-uuid",
    "name": "Arbeitsvertrag Standard",
    "description": "Standard-Arbeitsvertrag fuer befristete Beschaeftigung",
    "content": "# Arbeitsvertrag\n\nZwischen **{{ employer.company }}**...",
    "isSystemTemplate": true,
    "organizationId": null,
    "status": "Aktiv",
    "statusKey": "contract_template_status.active",
    "createdAt": "2026-03-01 10:00:00",
    "lastModified": "2026-03-15 14:30:00",
    "usedPlaceholders": ["employer.company", "employee.fullName", "contract.startDate"],
    "requiredFields": ["employer.company", "employee.firstName", "employee.lastName", "contract.startDate"]
  }
]

GET/staffsign/contract_templates/{id}Template abrufen

Gibt das vollständige Template zurück — identische Struktur wie in der Listenansicht.

Request Body: Kein Body erforderlich.

Response 200 OK

{
  "id": "template-uuid",
  "name": "Arbeitsvertrag Standard",
  "description": "Standard-Arbeitsvertrag fuer befristete Beschaeftigung",
  "content": "# Arbeitsvertrag\n\nZwischen **{{ employer.company }}**, vertreten durch {{ employer.fullName }}...",
  "renderLogo": true,
  "isSystemTemplate": false,
  "organizationId": "org-uuid",
  "status": "Aktiv",
  "statusKey": "contract_template_status.active",
  "createdAt": "2026-03-01 10:00:00",
  "lastModified": "2026-03-15 14:30:00",
  "usedPlaceholders": [
    "employer.company",
    "employer.fullName",
    "employee.fullName",
    "employee.dateOfBirth",
    "contract.startDate",
    "contract.compensationAmount"
  ],
  "requiredFields": [
    "contract.compensationAmount",
    "contract.startDate",
    "employee.dateOfBirth",
    "employee.firstName",
    "employee.lastName",
    "employer.company",
    "employer.firstName",
    "employer.lastName"
  ]
}

PATCH/staffsign/contract_templates/{id}Template aktualisieren

Aktualisiert eine bestehende Vorlage. System-Templates können nicht aktualisiert werden.

Request Body

{
  "name": "Arbeitsvertrag Befristet (aktualisiert)",
  "content": "# Arbeitsvertrag\n\nZwischen **{{ employer.company }}**...",
  "description": "Aktualisierte Vorlage",
  "renderLogo": false
}

Request-Felder

Feld	Typ	Pflicht	Beschreibung
name	string	Ja	Name (2–255 Zeichen)
content	string	Ja	Template-Inhalt (min. 10 Zeichen)
description	string	Nein	Beschreibung (max. 1000 Zeichen)
renderLogo	boolean	Nein	Organisations-Logo im PDF-Header rendern

Response 204 No Content

// 204 No Content — kein Response-Body

POST/staffsign/contract_templates/{id}/activateTemplate aktivieren

Setzt ein Draft-Template auf aktiv, sodass es für neue Verträge verwendet werden kann.

Request Body

// // Kein Request-Body erforderlich — kein Response-Body

Response

// 204 No Content — kein Response-Body

Voraussetzung: Template muss Status contract_template_status.draft haben.

DELETE/staffsign/contract_templates/{id}Template archivieren

Archiviert ein Template. Archivierte Templates können nicht mehr für neue Verträge verwendet werden.

Request Body

// // Kein Request-Body erforderlich — kein Response-Body

Response

// 204 No Content — kein Response-Body

POST/staffsign/contract_templates/validateTemplate validieren

Validiert ein Template ohne es zu speichern. Prüft Platzhalter-Syntax und unbekannte Variablen.

Request Body (identisch zu POST /contract_templates)

{
  "name": "Arbeitsvertrag Befristet",
  "description": "Vorlage fuer befristete Arbeitsvertraege im Promotionbereich",
  "content": "# Arbeitsvertrag\n\nZwischen **{{ employer.company }}**, vertreten durch {{ employer.fullName }},\nnachfolgend \"Arbeitgeber\",\n\nund **{{ employee.fullName }}**, geb. am {{ employee.dateOfBirth }},\nnachfolgend \"Arbeitnehmer\".\n\n## § 1 Beginn und Dauer\n\nDas Arbeitsverhaeltnis beginnt am {{ contract.startDate }}.",
  "renderLogo": true
}

Response — 204 bei Erfolg, 422 bei Validierungsfehlern

// 204 No Content — kein Response-Body

5. Webhooks

Webhooks benachrichtigen Ihr System automatisch per HTTP POST bei relevanten Ereignissen. Konfiguration über iPM-Dashboard → staffSign → Webhooks. Pro Organization können mehrere Webhooks eingerichtet werden.

5.1 Events

Event	Beschreibung	Auslöser
contract.created	Vertrag wurde erstellt	Nach Erstellung (Draft)
contract.sent	Vertrag zur Signatur versendet	Nach Versand an Teilnehmer
contract.recipient_signed	Empfänger hat signiert	Paperless meldet Empfänger-Signatur
contract.organization_signed	Organization hat signiert	Paperless meldet Organisations-Signatur
contract.completed	Alle Signaturen abgeschlossen	Letzte Signatur abgeschlossen
contract.document_ready	Signiertes PDF ist abrufbar	Paperless stellt Dokument bereit
contract.cancelled	Vertrag wurde storniert	Stornierung durch Organization
contract.expired	Vertrag ist abgelaufen	Signaturfrist überschritten
identification.completed	eID-Identifikation abgeschlossen	QES-Identifikation erfolgreich

contract.completed vs. contract.document_ready: completed feuert wenn alle Teilnehmer signiert haben. document_ready feuert wenn das PDF tatsächlich abrufbar ist — kann zeitlich versetzt sein. Für automatisierte Dokumentenabholung ist document_ready das relevantere Event.

5.2 Payload-Format

Eingehender Webhook-Request

POST https://ihr-system.example.com/webhook
Content-Type: application/json
X-Webhook-Signature: sha256=a1b2c3d4e5f6...
X-Webhook-Event: contract.recipient_signed

{
  "event": "contract.recipient_signed",
  "timestamp": "2026-03-31T14:45:00+00:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Versendet",
    "statusKey": "contract_status.sent",
    "participants": [
      { "role": "Arbeitgeber", "signedAt": null },
      { "role": "Arbeitnehmer", "signedAt": "2026-03-31T14:45:00+00:00" }
    ],
    ...
  }
}

Das data-Feld enthält die vollständige Contract-Repräsentation (ohne renderedContent und qesVerifiedAt).

5.3 Signatur-Verifizierung

Header: X-Webhook-Signature: sha256=<hex-digest>. Berechnung: HMAC-SHA256(request_body, webhook_secret).

PHP

$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$payload   = file_get_contents('php://input');
$secret    = 'ihr-webhook-secret';
$expected  = 'sha256=' . hash_hmac('sha256', $payload, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}
$data = json_decode($payload, true);

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Python

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

5.4 Retry, Timeout & Auto-Deaktivierung

Retry-Logik

Versuch	Wartezeit
1. Retry	~10 s
2. Retry	~40 s
3. Retry	~160 s

Nach 3 Retries → aufgegeben.

Timeout

10 Sekunden. Aufwändige Verarbeitung asynchron ausführen, sofort HTTP 200 zurückgeben.

Auto-Deaktivierung

Nach 30 Fehlern automatisch deaktiviert. Im iPM-Dashboard reaktivierbar. Eine erfolgreiche Zustellung (HTTP 2xx) setzt den Fehlerzähler zurück.

6. MCP-Server (KI-Agent-Integration)

Nativer MCP-Server für KI-Agenten. Gleiche Authentifizierung wie die REST-API. 12 Tools + 2 Resources.

6.1 Konfiguration

MCP-Endpoint: https://www.promotionbasis.de/api/mcp

Claude Desktop

{
  "mcpServers": {
    "staffsign": {
      "type": "http",
      "url": "https://www.promotionbasis.de/api/mcp",
      "headers": {
        "X-Api-Key": "<api-key>"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "staffsign": {
      "type": "http",
      "url": "https://www.promotionbasis.de/api/mcp",
      "headers": {
        "X-Api-Key": "<api-key>"
      }
    }
  }
}

Microsoft Copilot

{
  "mcpServers": {
    "staffsign": {
      "type": "http",
      "url": "https://www.promotionbasis.de/api/mcp",
      "headers": {
        "X-Api-Key": "<api-key>"
      }
    }
  }
}

6.2 Tools & Resources

Contract-Tools

Tool	Beschreibung	Parameter
search_contracts	Contracts auflisten mit Filter	searchTerm?, status?, limit?, offset?
get_contract	Vollständige Contract-Details	id (UUID)
create_contract	Neuen Vertrag aus Template erstellen	contractTemplateId, signatureLevel, participants[], terms, ...
send_contract	Draft-Vertrag versenden	id (UUID)
cancel_contract	Versendeten Vertrag stornieren	id (UUID)
delete_contract	Draft-Vertrag löschen	id (UUID)

Template-Tools

Tool	Beschreibung	Parameter
search_contract_templates	Templates suchen	searchTerm?, status?, limit?, offset?
get_contract_template	Vollständiges Template abrufen	id (UUID)
create_contract_template	Neues Template erstellen	name, content, description?
update_contract_template	Template aktualisieren	id (UUID), name, content, description?
activate_contract_template	Draft-Template aktivieren	id (UUID)
archive_contract_template	Template archivieren	id (UUID)

Resources

Resource	URI	Beschreibung
contract_template_placeholders	contract-templates://placeholders	Alle verfügbaren Platzhalter, gruppiert
create_contract_schema	contracts://create-schema	Schema + Beispiel-Request + alle Enum-Werte

6.3 Empfohlener Workflow

1
Resource lesen:contract_template_placeholders — Platzhalter verstehen
2
Templates suchen:search_contract_templates — passende Vorlage finden
3
Template abrufen:get_contract_template — Content und requiredFields prüfen
4
Schema lesen:create_contract_schema — Enum-Werte und Struktur verstehen
5
Vertrag erstellen:create_contract mit sendImmediately: false — als Draft anlegen
6
Vertrag versenden:send_contract — zur Signatur freigeben
7
Status prüfen:get_contract — Signatur-Status abfragen

7. Fehlerbehandlung

7.1 Validierungsfehler (422)

Response 422

{
  "violations": [
    {
      "propertyPath": "signatureLevel",
      "message": "Dieser Wert sollte nicht leer sein.",
      "code": "c1051bb4-d103-4f74-8988-acbcafc7fdc3"
    },
    {
      "propertyPath": "participants",
      "message": "Diese Gruppe muss mindestens 2 Elemente enthalten.",
      "code": "bef8e338-6ae5-4caf-b8e2-50e7b0579e69"
    }
  ]
}

7.2 Häufige Fehlerszenarien

Szenario	Code	Ursache
Fehlender API-Key	401	X-Api-Key-Header nicht gesetzt
Ungültiger API-Key	401	Key existiert nicht oder ist deaktiviert
Falsches Format	401	Key hat nicht das Format {id}.{random}
Validierungsfehler	422	Pflichtfelder fehlen oder ungültige Werte
Vertrag nicht im Draft	422	Versuch, versendeten Vertrag zu löschen
Vertrag nicht stornierbar	422	Vertrag nicht im Status sent
Template nicht aktiv	422	Vertrag mit Draft- oder archiviertem Template
Doppelte E-Mail	422	Zwei Teilnehmer mit identischer E-Mail
Ungültige Platzhalter	422	Template enthält unbekannte Variablen
Nicht gefunden	404	ID existiert nicht oder gehört zu anderer Organization

8. Datenstrukturen

8.1 Contract

Contract — vollständige Struktur (Einzelabruf)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "org-uuid",
  "jobPostingId": null,
  "contractTemplateId": "template-uuid",
  "contractTemplateName": "Arbeitsvertrag Standard",
  "contractType": "Arbeitsvertrag",
  "contractTypeKey": "contract_type.employment",
  "status": "Entwurf",
  "statusKey": "contract_status.draft",
  "signatureLevel": "Qualifizierte elektronische Signatur",
  "signatureLevelKey": "signature_level.qes",
  "participants": [
    {
      "id": "participant-uuid-1",
      "role": "Arbeitgeber",
      "roleKey": "contract_participant_role.employer",
      "signingMethod": "Digitale Signatur",
      "signingMethodKey": "signing_method.digital",
      "participantId": null,
      "participantData": {
        "email": "hr@acme-staffing.de",
        "firstName": "Anna",
        "lastName": "Schmidt",
        "dateOfBirth": null,
        "company": "ACME Staffing GmbH",
        "gender": "gender.female",
        "phone": "+49 30 123456",
        "street": "Musterstrasse 123",
        "zipcode": "10115",
        "city": "Berlin",
        "country": "country.de"
      },
      "signedAt": null,
      "qesVerifiedAt": null
    }
  ],
  "startDate": "2026-04-01",
  "endDate": "2026-09-30",
  "compensationType": "Stuendlich",
  "compensationTypeKey": "compensation_type.hourly",
  "compensationAmount": "18.5",
  "sentAt": null,
  "createdAt": "2026-03-31 14:30:00",
  "autoDeliverSignedDocument": true,
  "signedDocumentDeliveredAt": null,
  // Nur beim Einzelabruf (GET /contracts/{id}):
  "expiresAt": null,
  "renderedContent": "<h1>Arbeitsvertrag</h1>...",
  "compensationDescription": "Stundenlohn zzgl. Zuschlaege",
  "location": "Berlin, verschiedene Einsatzorte",
  "employmentType": "Befristet",
  "employmentTypeKey": "employment_type.temporary",
  "workDescription": "Promotion- und Messeeinsaetze",
  "probationPeriod": "6 Monate",
  "cancellationPeriod": "2 Wochen zum Monatsende",
  "scheduleType": "Flexibel",
  "scheduleTypeKey": "schedule_type.flexible",
  "workingTimeDescription": "Ca. 20-40 Stunden pro Woche",
  "externalDocumentId": null,
  "signedDocumentUrl": null,
  "auditTrailPdfUrl": null,
  "sealedPdfUrl": null
}

Feld	Typ	Beschreibung
id	UUID	Vertrags-ID
organizationId	UUID	Organization-ID
jobPostingId	UUID\|null	Zugehörige Stellenanzeige
contractTemplateId	UUID	ID der verwendeten Vorlage
contractTemplateName	string	Name der Vorlage
contractType / contractTypeKey	string	Vertragstyp (lesbar / maschinenlesbar)
status / statusKey	string	Status (lesbar / maschinenlesbar, → Enum 9.4)
signatureLevel / signatureLevelKey	string	Signatur-Stufe (→ Enum 9.1)
participants	array	Teilnehmer mit Rollen, Methoden, Daten, signedAt, qesVerifiedAt
startDate	string	Vertragsbeginn (YYYY-MM-DD)
endDate	string\|null	Vertragsende (YYYY-MM-DD)
compensationType / compensationTypeKey	string	Vergütungsart (→ Enum 9.5)
compensationAmount	string	Vergütungsbetrag
sentAt	string\|null	Versandzeitpunkt
createdAt	string	Erstellungszeitpunkt
expiresAt *	string\|null	Ablaufzeitpunkt der Signaturfrist
renderedContent *	string	Gerenderter HTML-Inhalt
compensationDescription *	string\|null	Beschreibung der Vergütung
location *	string\|null	Arbeitsort
employmentType / employmentTypeKey *	string\|null	Beschäftigungsart (→ Enum 9.6)
workDescription *	string\|null	Tätigkeitsbeschreibung
probationPeriod *	string\|null	Probezeit
cancellationPeriod *	string\|null	Kündigungsfrist
scheduleType / scheduleTypeKey *	string\|null	Arbeitszeitmodell (→ Enum 9.7)
workingTimeDescription *	string\|null	Beschreibung der Arbeitszeit
externalDocumentId *	string\|null	Paperless-Dokument-ID
signedDocumentUrl *	string\|null	URL zum signierten PDF (nach allen Signaturen)
auditTrailPdfUrl *	string\|null	URL zum Audit-Trail-PDF
sealedPdfUrl *	string\|null	URL zum versiegelten PDF

* Nur beim Einzelabruf (GET /contracts/{id}) verfügbar, nicht in der Listenansicht.

8.2 ContractTemplate

ContractTemplate — vollständige Struktur

{
  "id": "template-uuid",
  "name": "Arbeitsvertrag Standard",
  "description": "Standard-Arbeitsvertrag fuer befristete Beschaeftigung",
  "content": "# Arbeitsvertrag\n\nZwischen **{{ employer.company }}**, vertreten durch {{ employer.fullName }}...",
  "renderLogo": true,
  "isSystemTemplate": false,
  "organizationId": "org-uuid",
  "status": "Aktiv",
  "statusKey": "contract_template_status.active",
  "createdAt": "2026-03-01 10:00:00",
  "lastModified": "2026-03-15 14:30:00",
  "usedPlaceholders": [
    "employer.company",
    "employer.fullName",
    "employee.fullName",
    "employee.dateOfBirth",
    "contract.startDate",
    "contract.compensationAmount"
  ],
  "requiredFields": [
    "contract.compensationAmount",
    "contract.startDate",
    "employee.dateOfBirth",
    "employee.firstName",
    "employee.lastName",
    "employer.company",
    "employer.firstName",
    "employer.lastName"
  ]
}

Feld	Typ	Beschreibung
id	UUID	Template-ID
name	string	Name (2–255 Zeichen)
description	string\|null	Optionale Beschreibung
content	string	Template-Inhalt (Markdown + Twig-Syntax)
isSystemTemplate	boolean	true bei von staffSign bereitgestellten Systemvorlagen
organizationId	UUID\|null	Organization-ID (null bei Systemvorlagen)
status / statusKey	string	Status (lesbar / maschinenlesbar, → Enum 9.9)
createdAt	string	Erstellungszeitpunkt (YYYY-MM-DD HH:MM:SS)
lastModified	string	Letzte Änderung
usedPlaceholders	string[]	Alle im Template verwendeten Platzhalter-Variablen
requiredFields	string[]	Benötigte Eingabefelder (computed wie fullName → firstName + lastName)

Hinweis: Templates liefern in Liste und Einzelabruf die identische vollständige Struktur.

8.3 ParticipantData

Feld	Typ	Pflicht	Beschreibung
email	string	Ja*	E-Mail-Adresse (Pflicht für signing_method.digital)
firstName	string	Nein	Vorname (max. 255 Zeichen)
lastName	string	Nein	Nachname (max. 255 Zeichen)
dateOfBirth	string	Nein	Geburtsdatum (YYYY-MM-DD)
company	string	Nein	Firmenname (max. 255 Zeichen)
gender	string	Nein	Geschlecht (→ Enum 9.8)
phone	string	Nein	Telefonnummer (max. 30 Zeichen)
street	string	Nein	Straße (max. 255 Zeichen)
zipcode	string	Nein	Postleitzahl (max. 20 Zeichen)
city	string	Nein	Stadt (max. 255 Zeichen)
country	string	Nein	Land (→ Enum 9.10)

9. Enum-Referenz

9.1 SignatureLevel

Wert	Beschreibung
signature_level.aes	Fortgeschrittene elektronische Signatur (AES)
signature_level.qes	Qualifizierte elektronische Signatur (QES)

9.2 SigningMethod

Wert	Beschreibung
signing_method.digital	Digitale Signatur über Paperless (Online-Signatur)
signing_method.manual	Manuelle Signatur (Offline, z.B. auf Papier)

9.3 ContractParticipantRole

Jeder Vertrag benötigt mindestens 2 Teilnehmer mit unterschiedlichen Rollen.

Wert	Beschreibung
contract_participant_role.employer	Arbeitgeber
contract_participant_role.employee	Arbeitnehmer
contract_participant_role.contract_creator	Vertragsersteller (generisch)
contract_participant_role.contract_recipient	Vertragsempfänger (generisch)
contract_participant_role.landlord	Vermieter
contract_participant_role.tenant	Mieter

9.4 ContractStatus

Wert	Beschreibung
contract_status.draft	Entwurf — noch nicht versendet
contract_status.sent	Versendet — wartet auf Signaturen
contract_status.signed	Alle Teilnehmer haben signiert
contract_status.expired	Abgelaufen — Signaturfrist überschritten
contract_status.cancelled	Storniert

9.5 CompensationType

Wert	Beschreibung
compensation_type.hourly	Stündlich
compensation_type.daily	Täglich
compensation_type.monthly	Monatlich
compensation_type.one_time	Einmalig
compensation_type.none	Keine Vergütung

9.6 EmploymentType

Wert	Beschreibung
employment_type.contractor	Freiberuflich / Werkvertrag
employment_type.full_time	Vollzeit
employment_type.part_time	Teilzeit
employment_type.temporary	Befristet
employment_type.part_time_mini	Minijob
employment_type.student	Werkstudent
employment_type.training	Ausbildung

9.7 ScheduleType

Wert	Beschreibung
schedule_type.daily	Täglich (feste Zeiten)
schedule_type.weekly	Wöchentlich
schedule_type.monthly	Monatlich
schedule_type.flexible	Flexibel

9.8 Gender

Wert	Beschreibung
gender.male	Männlich
gender.female	Weiblich
gender.diverse	Divers

9.9 ContractTemplateStatus

Wert	Beschreibung
contract_template_status.draft	Entwurf
contract_template_status.active	Aktiv — kann für Verträge verwendet werden
contract_template_status.archived	Archiviert — nicht mehr verwendbar

9.10 Country

Alle ISO-3166-1 Alpha-2-Codes werden unterstützt (z.B. country.us, country.gb, country.pl, ...).

Wert	Beschreibung
country.de	Deutschland
country.at	Österreich
country.ch	Schweiz
country.nl	Niederlande
country.fr	Frankreich

Jetzt Account erstellen