Institution

The institution is your own company record in Zeitstrom. The API is always scoped to the organization your token belongs to, so the collection contains exactly one institution: yours. Use it to read your organization's master data, update the company address, and manage the organization-wide default settings that apply to all employees unless overridden at group or employee level.

If your API token is restricted to specific permissions, it needs the matching scope for each operation: institutions:view to list and retrieve the institution and to read the billing address, institutions:edit for updates, settings:institutions:view to read the current settings (the historical settings endpoint requires no specific scope), and settings:institutions:edit to change settings. Because a settings update responds with the full current settings, restricted tokens need settings:institutions:view in addition to settings:institutions:edit to update settings. Requests without the required permission return 403 Forbidden.

The Institution Object

Name
id
Type
string (UUID)
Description
Unique identifier for the institution. Read-only.
Name
created_at
Type
string (ISO 8601, local time)
Description
When the institution was created. Read-only.
Name
modified_at
Type
string (ISO 8601, local time)
Description
When the institution was last modified. Read-only.
Name
onboarded_at
Type
string (ISO 8601, local time) or null
Description
When the organization completed onboarding, or null if onboarding has not been completed yet. Read-only.
Name
name
Type
string
Description
The company name. Maximum length 128 characters.
Name
flags
Type
array of strings
Description
Feature flags enabled for the organization, e.g. projects or daily_reports. Empty array if no flags are set. Read-only.
Name
config
Type
object
Description
Organization-specific configuration used by the Zeitstrom apps, such as daily report form definitions (daily_report) and custom export configurations. The contents are managed by Zeitstrom and subject to change. Read-only.
Name
contact_person
Type
string
Description
Name of the primary contact person. Maximum length 128 characters.
Name
address
Type
string
Description
Street name of the company address. Maximum length 128 characters.
Name
number
Type
string
Description
Street number. Maximum length 10 characters.
Name
address_2
Type
string
Description
Additional address line. Maximum length 128 characters.
Name
zip_code
Type
string
Description
Postal code. Maximum length 8 characters.
Name
city
Type
string
Description
City. Maximum length 128 characters.
Name
country
Type
string
Description
Country. Maximum length 128 characters.
Name
brand
Type
string or null
Description
The brand the organization is registered under, e.g. zeitstrom. Read-only.
Name
plan
Type
string or null
Description
Identifier of the subscription plan, e.g. premium. The available values depend on the brand. Read-only.
Name
logo_7_2_light
Type
string or null
Description
Company logo in 7:2 aspect ratio for light backgrounds. Falls back to the reseller's logo if the organization has none. Read-only.
Name
logo_1_1_light
Type
string or null
Description
Company logo in 1:1 aspect ratio for light backgrounds. Falls back to the reseller's logo if the organization has none. Read-only.
Name
logo_7_2_dark
Type
string or null
Description
Company logo in 7:2 aspect ratio for dark backgrounds. Falls back to the reseller's logo if the organization has none. Read-only.
Name
logo_1_1_dark
Type
string or null
Description
Company logo in 1:1 aspect ratio for dark backgrounds. Falls back to the reseller's logo if the organization has none. Read-only.
Name
license
Type
object
Description
License status of the organization: expired (boolean), valid_until (date), restriction_date (date after which an expired account is restricted), and deletion_date (date after which an expired account is scheduled for deletion). Read-only.
Name
invoice_email_address
Type
string or null
Description
Email address invoices are sent to. For privacy reasons this field is only returned to administrator sessions — API tokens always read it as null. It can still be set via the update endpoint.

GET/api/v2/accounts/institutions/

List your Institution

Retrieve your organization. The response uses the standard paginated list format, but the result set always contains exactly one entry: the institution your API token belongs to. Use this endpoint to look up your institution's id for the detail endpoints below.

Request

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

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "e7a1f0d3-4c2b-4f6e-9a8d-1b2c3d4e5f60",
      "created_at": "2023-02-14T09:31:02",
      "modified_at": "2026-06-12T08:15:44",
      "onboarded_at": "2023-02-15T10:02:11",
      "name": "Muster Bau GmbH",
      "flags": ["projects"],
      "config": {
        "daily_report": [
          {
            "id": "default",
            "valid_from": "1970-01-01",
            "pdf_fields": [],
            "form_fields": [
              {
                "id": "weather",
                "type": "weather",
                "label": "Witterung",
                "config": {
                  "times": ["0800", "1200", "1600"],
                  "autofill_from_api": true
                }
              }
            ]
          }
        ]
      },
      "contact_person": "Max Mustermann",
      "address": "Hauptstraße",
      "number": "12",
      "address_2": "",
      "zip_code": "10115",
      "city": "Berlin",
      "country": "Deutschland",
      "brand": "zeitstrom",
      "plan": "premium",
      "logo_7_2_light": null,
      "logo_1_1_light": null,
      "logo_7_2_dark": null,
      "logo_1_1_dark": null,
      "license": {
        "expired": false,
        "valid_until": "2026-12-31",
        "restriction_date": "2027-02-11",
        "deletion_date": "2027-04-08"
      },
      "invoice_email_address": null
    }
  ]
}

GET/api/v2/accounts/institutions/:id/

Retrieve your Institution

Get your institution by its id. Only your own institution is accessible; requesting any other ID returns 404 Not Found. The response body is the same institution object as in the list response.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/accounts/institutions/e7a1f0d3-4c2b-4f6e-9a8d-1b2c3d4e5f60/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

PATCH/api/v2/accounts/institutions/:id/

Update your Institution

Update the master data of your organization. Only the fields listed below are writable; all other institution fields are read-only. PUT requests to the same URL are also accepted — with PUT, the name field is required, while PATCH allows partial updates.

The response contains only the writable fields.

Name
name
Type
string
Description
The company name. Maximum length 128 characters. Required for PUT.
Name
contact_person
Type
string
Description
Name of the primary contact person. Maximum length 128 characters.
Name
address
Type
string
Description
Street name. Maximum length 128 characters.
Name
number
Type
string
Description
Street number. Maximum length 10 characters.
Name
address_2
Type
string
Description
Additional address line. Maximum length 128 characters.
Name
zip_code
Type
string
Description
Postal code. Maximum length 8 characters.
Name
city
Type
string
Description
City. Maximum length 128 characters.
Name
country
Type
string
Description
Country. Maximum length 128 characters.
Name
invoice_email_address
Type
string or null
Description
Email address invoices are sent to. Must be a valid email address. Note that API tokens read this field back as null (see The Institution Object).

Request

curl -X PATCH "https://api.zeitstrom.com/api/v2/accounts/institutions/e7a1f0d3-4c2b-4f6e-9a8d-1b2c3d4e5f60/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_person": "Erika Beispiel",
    "invoice_email_address": "rechnung@musterbau.example"
  }'

Response

{
  "name": "Muster Bau GmbH",
  "contact_person": "Erika Beispiel",
  "address": "Hauptstraße",
  "number": "12",
  "address_2": "",
  "zip_code": "10115",
  "city": "Berlin",
  "country": "Deutschland",
  "invoice_email_address": "rechnung@musterbau.example"
}

GET/api/v2/accounts/institutions/:id/settings/

Institution Settings

Retrieve or update the organization-wide default settings, such as the default daily working times or the public holiday region. These defaults apply to all employees unless overridden at the employee group or employee level. Settings are grouped by category: both the response and the update payload use the nested structure {"<category>": {"<setting>": <value>}}.

To update settings, send a POST request with the same nested structure. Unlike employee-level settings, the update is a merge: only the settings included in the payload are changed, and any institution-level setting not included in the payload keeps its current value. The response of a successful update is the full set of currently applicable settings.

Retrieve Settings

curl -X GET "https://api.zeitstrom.com/api/v2/accounts/institutions/e7a1f0d3-4c2b-4f6e-9a8d-1b2c3d4e5f60/settings/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Update Settings

curl -X POST "https://api.zeitstrom.com/api/v2/accounts/institutions/e7a1f0d3-4c2b-4f6e-9a8d-1b2c3d4e5f60/settings/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "working_session": {
      "daily_working_times": [8, 8, 8, 8, 8, 0, 0]
    }
  }'

Response

{
  "working_session": {
    "daily_working_times": [8, 8, 8, 8, 8, 0, 0],
    "public_holidays": "active",
    "country": "DE",
    "use_working_hour_balance": "active",
    "weekly_working_time": 40
  }
}

Unknown setting keys — including deprecated compatibility values such as weekly_working_time that appear in the retrieve response — are silently ignored on update. Only settings that exist in the current settings catalog are persisted, and each value is validated against the setting's type (invalid values return a 400 validation error).

GET/api/v2/accounts/institutions/:id/settings-historical/

Historical Settings

Retrieve all organization-wide settings including values that are no longer or not yet applicable. Each setting is returned as a list of values with their validity range. Unlike other datetimes in this API, the valid_from and valid_before bounds are returned in UTC with a Z suffix.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/accounts/institutions/e7a1f0d3-4c2b-4f6e-9a8d-1b2c3d4e5f60/settings-historical/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "working_session": {
    "daily_working_times": [
      {
        "valid_from": "2023-12-31T23:00:00Z",
        "valid_before": "2024-05-31T22:00:00Z",
        "value": [8, 8, 8, 8, 8, 0, 0]
      },
      {
        "valid_from": "2024-05-31T22:00:00Z",
        "valid_before": null,
        "value": [6, 6, 6, 6, 6, 0, 0]
      }
    ]
  }
}

GET/api/v2/accounts/institutions/:id/billing-address/

Billing Address

Retrieve the billing address of your organization as individual components plus a single pre-formatted string. The formatted value joins the company name, street with street number, additional address line, postal code with city, and country, skipping any empty parts.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/accounts/institutions/e7a1f0d3-4c2b-4f6e-9a8d-1b2c3d4e5f60/billing-address/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "name": "Muster Bau GmbH",
  "address": "Hauptstraße",
  "address_2": "",
  "zip_code": "10115",
  "city": "Berlin",
  "country": "Deutschland",
  "formatted": "Muster Bau GmbH, Hauptstraße 12, 10115 Berlin, Deutschland"
}

The street number is included in the formatted string but is not returned as a separate field by this endpoint. Read it from the institution object if you need it individually.