Zusatzfelder abfragen

GET


																https://…/office/api/additionalCustomerFields

Diese Schnittstelle gehört zur Geschützten API und benötigt einen API-Schlüssel. Den Token erstellen Sie in Ihrem Kalender unter den globalen Einstellungen als API Zugang – siehe API-Schnittstellen.

Diese Schnittstelle liefert die Konfiguration aller aktiven Zusatzfelder des Standorts, zu dem der API-Schlüssel gehört – Kundenfelder (Stammdaten) ebenso wie terminbezogene Felder, Felder, die nur im Kalender oder am Termin angezeigt werden, ausgeblendete Felder und die standortspezifischen Felder dieses Standorts. Archivierte (gelöschte) Felder sind nicht enthalten. Mit dem zurückgegebenen keyName lassen sich die Zusatzfelder eines Kunden anschließend über Kundendaten ändern setzen.

Authentifizierung

Der API-Token wird als URL-Parameter token übergeben. Sie erzeugen ihn im Office unter Module › API-Zugang; ein Token kann ein Ablaufdatum haben. Die Felder werden immer für den Standort geliefert, zu dem der Token gehört.

Beispielaufruf

curl -s 'https://demo.belbo.com/office/api/additionalCustomerFields?token=IHR_TOKEN&locale=de'

Ersetzen Sie demo durch Ihre Kundenkennung, also https://<kundenkennung>.belbo.com.

Antwort

Die Antwort ist ein JSON-Array mit einem Objekt je Zusatzfeld, sortiert nach listOrder. Die Beispielantwort zeigt drei typische Fälle: ein Kundenfeld mit Auswahlliste, ein terminbezogenes Textfeld, das nur im Kalender erscheint, und ein ausgeblendetes Datumsfeld.

Name	Typ	Beschreibung
`id`	number	Interne ID des Feldes.
`keyName`	string	Technischer Schlüssel. Er erscheint als `key` in den `additionalFields` der Kunden-Endpunkte (customers, customerForMobile) und wird bei updateCustomer zum Setzen von Werten verwendet.
`name`	string	Anzeigename, bei gesetztem `locale` gegebenenfalls übersetzt.
`type`	string	Feldtyp, einer von: `text`, `date`, `textArea`, `selection`, `checkbox`, `checkbox_group`, `birthday`, `image`, `link`, `multipleImages`, `document`, `multipleDocuments`, `multipleProducts`, `rating`, `servicer`, `customer`, `member`, `card`, `iban`, `bic`, `pictureMarking`, `directDebitMandateDate`, `recipes`, `contractOverview`, `language`, `other`.
`description`	string \| null	Beschreibung. Bei `selection` und `checkbox_group` steht hier die zeilengetrennte Auswahlliste.
`selectItems`	string[] \| null	Auswahlwerte – nur bei `selection` und `checkbox_group`, sonst `null`.
`valueRequired`	boolean	Pflichtfeld.
`validatorRegexp`	string \| null	Regulärer Ausdruck zur Validierung des Werts.
`errorMessage`	string \| null	Fehlermeldung bei ungültigem Wert, bei gesetztem `locale` gegebenenfalls übersetzt.
`icon`	string \| null	Name des Icons.
`tab`	object \| null	Reiter in der Kundenkartei, als `{id, name}`.
`appointmentSpecific`	boolean	Der Wert gehört zum Termin statt zum Kunden.
`specificForLocationId`	number \| null	Das Feld gilt nur für diesen Standort; `null` bedeutet: alle Standorte.
`hidden`	boolean	Im Office ausgeblendet.
`visibleForCustomer`	boolean	Für Endkunden bei der Online-Buchung bzw. Registrierung sichtbar.
`showInCalendar`	boolean	Wird in den Termindetails im Kalender angezeigt.
`showInAppointment`	boolean	Wird in der Kalendervorschau des Termins angezeigt.
`showInAppointmentEntry`	boolean	Wird bei der Terminerfassung abgefragt.
`showInDetailScreen`	boolean	Wird in der Kundendetailansicht angezeigt.
`showInCustomerSearchPreview`	boolean	Wird in der Kundensuche angezeigt.
`privacyConfidential`	boolean	Datenschutzsensibles Feld.
`listOrder`	number	Sortierreihenfolge in der Kundenkartei. Nach diesem Wert ist die Antwort sortiert.
`listOrderOnline`	number	Sortierreihenfolge im Online-Formular.
`listOrderAppointment`	number	Sortierreihenfolge am Termin.

Fehlerfälle

Status	Meldung	Ursache
`200`	`Access denied`	Der Token ist ungültig oder abgelaufen. Die Antwort ist reiner Text, kein JSON – so antworten alle Endpunkte der Geschützten API.

Hinweise zur Verwendung

keyName für updateCustomer: Um den Wert eines Zusatzfelds bei einem Kunden zu setzen, übergeben Sie bei Kundendaten ändern den keyName aus dieser Antwort, zum Beispiel {"additionalFields":{"hauttyp":"trocken"}}.
Binärfelder: Felder der Typen image, multipleImages, document, multipleDocuments und pictureMarking werden zwar aufgelistet, können aber nicht per updateCustomer gesetzt werden.
Terminbezogene Felder: Bei appointmentSpecific = true gehört der Wert zum Termin, nicht zum Kunden.

Parameter

Name	Übergabe
`token`	URL-Parameter Pflicht
Beispiel`IHR_TOKEN` string – API-Token, erzeugt im Office unter Module › API-Zugang. Er legt zugleich den Standort fest, dessen Zusatzfelder geliefert werden.
`locale`	URL-Parameter Optional
Beispiel`de` string – Sprache, z. B. "de", "en", "nl" oder "fr". Liefert name, description und errorMessage übersetzt, sofern eine Übersetzung existiert, sonst den Standardtext.

Struktur zuletzt mit der Postman-Collection abgeglichen: 01.10.2026

Beispielantwort

200 Zusatzfelder des Standorts

[
    {
        "id": 4711,
        "keyName": "hauttyp",
        "name": "Hauttyp",
        "type": "selection",
        "description": "normal\ntrocken\nfettig\nMischhaut",
        "selectItems": [
            "normal",
            "trocken",
            "fettig",
            "Mischhaut"
        ],
        "valueRequired": false,
        "validatorRegexp": null,
        "errorMessage": null,
        "icon": "face",
        "tab": {
            "id": 12,
            "name": "Kosmetik"
        },
        "appointmentSpecific": false,
        "specificForLocationId": null,
        "hidden": false,
        "visibleForCustomer": true,
        "showInCalendar": false,
        "showInAppointment": false,
        "showInAppointmentEntry": false,
        "showInDetailScreen": true,
        "showInCustomerSearchPreview": true,
        "privacyConfidential": false,
        "listOrder": 1,
        "listOrderOnline": 1,
        "listOrderAppointment": 0
    },
    {
        "id": 4712,
        "keyName": "behandlungsnotiz",
        "name": "Behandlungsnotiz",
        "type": "text",
        "description": null,
        "selectItems": null,
        "valueRequired": false,
        "validatorRegexp": null,
        "errorMessage": null,
        "icon": null,
        "tab": null,
        "appointmentSpecific": true,
        "specificForLocationId": null,
        "hidden": false,
        "visibleForCustomer": false,
        "showInCalendar": true,
        "showInAppointment": false,
        "showInAppointmentEntry": false,
        "showInDetailScreen": false,
        "showInCustomerSearchPreview": false,
        "privacyConfidential": false,
        "listOrder": 2,
        "listOrderOnline": 0,
        "listOrderAppointment": 1
    },
    {
        "id": 4713,
        "keyName": "letzteHautanalyse",
        "name": "Letzte Hautanalyse",
        "type": "date",
        "description": null,
        "selectItems": null,
        "valueRequired": false,
        "validatorRegexp": null,
        "errorMessage": null,
        "icon": null,
        "tab": {
            "id": 12,
            "name": "Kosmetik"
        },
        "appointmentSpecific": false,
        "specificForLocationId": null,
        "hidden": true,
        "visibleForCustomer": false,
        "showInCalendar": false,
        "showInAppointment": false,
        "showInAppointmentEntry": false,
        "showInDetailScreen": false,
        "showInCustomerSearchPreview": false,
        "privacyConfidential": false,
        "listOrder": 3,
        "listOrderOnline": 0,
        "listOrderAppointment": 0
    }
]