Contracts

Manage legal contracts such as Data Processing Agreements (DPA) and subcontractor agreements. Contracts go through a lifecycle of preview and signing.

Reading, creating, and deleting contracts requires the contracts:view permission on your API token. Signing requires the separate contracts:sign permission. The contract states and contract types endpoints only require a valid token.

The Contract Object

Name
id
Type
string (UUID)
Description
Unique identifier for the contract.
Name
created_at
Type
string (ISO 8601)
Description
Timestamp when the contract was created.
Name
signed_at
Type
string (ISO 8601) or null
Description
Timestamp when the contract was signed.
Name
revoked_at
Type
string (ISO 8601) or null
Description
Timestamp when the contract was revoked.
Name
state
Type
string
Description
Current state: preview, signed, or revoked. Note that there is no API endpoint to revoke a contract; the revoked state can only appear on contracts revoked outside of this API.
Name
type
Type
string
Description
Contract type: dpa, tom, or subcontractors.

GET/api/v2/contracts/contracts/

List all Contracts

Retrieve a list of contracts.

Query Parameters

Name
states
Type
string
Description
Filter by state: preview, signed, or revoked. Multiple values can be combined with a pipe, e.g. ?states=preview|signed.
Name
types
Type
string
Description
Filter by type: dpa, tom, or subcontractors. Multiple values can be combined with a pipe, e.g. ?types=dpa|tom.
Name
ids
Type
string
Description
Filter by contract IDs. Multiple UUIDs can be combined with a pipe.
Name
order
Type
string
Description
Order the results by created_at or signed_at. Prefix a field with - for descending order, and combine multiple fields with a pipe, e.g. ?order=-created_at. Other fields return a validation error.
Name
limit
Type
integer
Description
Maximum number of results per page. Defaults to 100, maximum is 1000.
Name
offset
Type
integer
Description
Number of results to skip for pagination.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/contracts/contracts/?states=signed" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "3f9c2b1e-8a4d-4f6b-9c2e-7d5a1b3f8e4c",
      "created_at": "2024-01-10T10:00:00",
      "signed_at": "2024-01-15T14:30:00",
      "revoked_at": null,
      "state": "signed",
      "type": "dpa"
    }
  ]
}

GET/api/v2/contracts/contracts/:id/

Retrieve a Contract

Get details of a specific contract.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/contracts/contracts/3f9c2b1e-8a4d-4f6b-9c2e-7d5a1b3f8e4c/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

GET/api/v2/contracts/contracts/:id/preview/

Preview a Contract

Get an HTML preview of the contract document.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/contracts/contracts/3f9c2b1e-8a4d-4f6b-9c2e-7d5a1b3f8e4c/preview/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

GET/api/v2/contracts/contracts/:id/pdf/

Download as PDF

Download the contract as a PDF document. The response streams the file with content type application/pdf and a Content-Disposition of inline; filename=contract.pdf.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/contracts/contracts/3f9c2b1e-8a4d-4f6b-9c2e-7d5a1b3f8e4c/pdf/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -o contract.pdf

POST/api/v2/contracts/contracts/:id/sign/

Sign a Contract

Digitally sign a contract. This changes its state from preview to signed and returns the updated contract object. Signing requires the contracts:sign permission. Metadata of the signing request (such as IP address and user agent) is stored as legal proof of the signature.

Only contracts in the preview state can be signed; signing a contract in any other state returns a validation error.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/contracts/contracts/3f9c2b1e-8a4d-4f6b-9c2e-7d5a1b3f8e4c/sign/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "3f9c2b1e-8a4d-4f6b-9c2e-7d5a1b3f8e4c",
  "created_at": "2024-01-10T10:00:00",
  "signed_at": "2024-01-15T14:30:00",
  "revoked_at": null,
  "state": "signed",
  "type": "dpa"
}

DELETE/api/v2/contracts/contracts/:id/

Delete a Contract

Delete a contract. Only contracts in the preview state can be deleted; attempting to delete a signed contract returns a validation error. A successful deletion returns an empty 204 No Content response.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/contracts/contracts/b7e4d2a9-1c3f-4e8b-a6d5-2f9c8b7a4e1d/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

POST/api/v2/contracts/contracts/data-processing-agreement/

Generate a DPA

Generate a new Data Processing Agreement with your organization's details. The new contract is created in the preview state and returned in the response.

Generating a DPA replaces any previous draft: all existing DPA contracts in the preview state are deleted before the new one is created. Signed contracts are not affected.

Name
representative
Type
string
Description
Name of the legal representative. Required.
Name
company
Type
string
Description
Company name. Required.
Name
street
Type
string
Description
Street address. Required.
Name
postal_code
Type
string
Description
Postal code. Required.
Name
city
Type
string
Description
City. Required.
Name
country
Type
string
Description
Country. Required.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/contracts/contracts/data-processing-agreement/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "representative": "Max Mustermann",
    "company": "Acme GmbH",
    "street": "Musterstraße 1",
    "postal_code": "10115",
    "city": "Berlin",
    "country": "Germany"
  }'

Response

{
  "id": "b7e4d2a9-1c3f-4e8b-a6d5-2f9c8b7a4e1d",
  "created_at": "2024-02-01T09:15:00",
  "signed_at": null,
  "revoked_at": null,
  "state": "preview",
  "type": "dpa"
}

GET/api/v2/contracts/contracts/guest-document/

Retrieve a Guest Document

Render a template legal document as HTML without creating a stored contract. This is useful for documents that do not require a signature, such as the list of subcontractors or the technical and organizational measures (TOM).

Query Parameters

Name
type
Type
string
Description
The document type to render: tom or subcontractors. Required. Other types return a validation error.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/contracts/contracts/guest-document/?type=subcontractors" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

GET/api/v2/contracts/contracts/guest-document-pdf/

Download a Guest Document PDF

Download a template legal document as a PDF without creating a stored contract. The response streams the file with content type application/pdf and a Content-Disposition of inline; filename=contract.pdf.

Query Parameters

Name
type
Type
string
Description
The document type to render: tom or subcontractors. Required. Other types return a validation error.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/contracts/contracts/guest-document-pdf/?type=tom" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -o tom.pdf

GET/api/v2/contracts/contracts/contract-states/

List Contract States

Retrieve the list of available contract states as id/label pairs. Labels are returned in German.

Query Parameters

Name
q
Type
string
Description
Filter by a case-insensitive substring of the label.
Name
ids
Type
string
Description
Filter by state IDs. Multiple values can be combined with a pipe, e.g. ?ids=preview|signed.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/contracts/contracts/contract-states/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    { "id": "preview", "label": "Entwurf" },
    { "id": "signed", "label": "Unterschrieben" },
    { "id": "revoked", "label": "Widerrufen" }
  ]
}

GET/api/v2/contracts/contracts/contract-types/

List Contract Types

Retrieve the list of available contract types as id/label pairs. Labels are returned in German. Supports the same q and ids query parameters as the contract states endpoint.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/contracts/contracts/contract-types/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    { "id": "dpa", "label": "Auftragsverarbeitungsvertrag" },
    { "id": "tom", "label": "Technische und organisatorische Maßnahmen nach Art. 32 DSGVO" },
    { "id": "subcontractors", "label": "Unterauftragnehmer" }
  ]
}