Batch

Adressprocessing Ablauf

1

Daten im CRM selektieren

Im CRM die zu verarbeitenden Datensätze selektieren – entweder alle Datensätze oder nur eine Teilmenge.

2

Erstellen von Data Groups

/api/AddressProcessing/AddDatagroup

• Daten werden in sogenannten Data Groups organisiert. Diese fungieren als Verarbeitungspakete und können mit einzelnen Schubladen in einem grossen Schrank verglichen werden.

  • Beispiel: Eine Data Group wird für wöchentliche Updates erstellt, eine andere für monatliche.

  • Hinweis: Sobald eine Data Group gestartet wird, werden die bestehenden Daten überschrieben.

3

Erstellung eines Batches

/api/AddressProcessing/Create

• Ein Batch ist die Hülle, die als Rahmen für die Verarbeitung dient. Er wird über den /batches Endpunkt erstellt.

4

Einstellungen konfigurieren

/api/AddressProcessing/SetBatchSettings

• Über SetBatchSettings können folgende Parameter festgelegt werden:

• InputMapping

• RangeBack

• WebhookUrl

5

Datei hochladen und Batch starten

/api/AddressProcessing/FileUpload

Hier erfolgt der Upload der Datei, die verarbeitet werden soll. Anschliessend startet der Batch basierend auf dem angegebenen UID-Schlüssel.

/api/AddressProcessing/Start

Statusabfrage: Der Fortschritt kann mittels /api/AddressProcessing/Detail überwacht werden. Dabei können laufende Module, Status der Dateien etc. eingesehen werden.

6

Download der Ergebnisse

/api/AddressProcessing/Detail

/api/AddressProcessing/FileDownload

• Im Detail ist die Liste aller Files mit einer eindeutigen File-ID enthalten. In Kombination mit der Batch-ID entsteht eine eindeutige Zuordnung.

• Die Resultate sind im .csv-Format verfügbar, wobei die Struktur auf tabulatorgetrennte Werte ausgelegt ist.

Funktionen

AddDatagroup

Fügt eine Datengruppe hinzu.

put

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/AddDatagroup

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

descriptionstringOptional

Responses

200

OK

No content

put

/api/addressprocessing/AddDatagroup

HTTPcURLJavaScriptPython

PUT /api/addressprocessing/AddDatagroup HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

No content

GetDataGroups

Listet die verfügbaren Datengruppen auf.

get

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/GetDatagroups

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

OK

No content

get

/api/addressprocessing/GetDatagroups

HTTPcURLJavaScriptPython

GET /api/addressprocessing/GetDatagroups HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

No content

Create

Erstellt eine Adressverarbeitung.

Request-Parameter	Erklärung
ordernr	Benutzerdefinierte Referenznummer, die zur eindeutigen Identifikation einer Bestellung vergeben werden kann, z. B. für spätere Rückfragen oder Abklärungen.
datagroupid	Eindeutige Identifikation der Data Group.
processid	Systemseitig vergebene ID für den Prozess. → Standardwert: 400
userDescription	Name der Kampagne oder des Batches.
BUSINESSCASE	Definiert den Prozessverlauf basierend auf vordefinierten Presets. → Standardwert: 0
product	Auswahl des gewünschten Produkts, z.B.: 1 Enrich: Anreicherung bestehender Daten. 2 Reference: Nur Analyse der Daten gegen die verfügbaren Datenquellen, keine Datenänderungen → Ergebnis: Analysebericht von Multisource und gegebenenfalls der Schweizerischen Post. 3 AdressUpdate: Aktualisierung bestehender Adressen.
processingdate	Definiert, wann der Batch gestartet werden soll (z.B. Hülle heute erstellen, Verarbeitung am Wochenende).
notificatioEmail	E-Mail-Adresse für Benachrichtigungen. Falls keine spezifische E-Mail-Adresse hinterlegt ist, wird standardmässig die E-Mail-Adresse des aktuell eingeloggten Benutzers verwendet.

post

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/Create

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/jsontext/jsonapplication/*+json

orderNrstringRequired

dataGroupIdinteger · int32Optional

dataGroupCodestring | nullableOptional

userDescriptionstring | nullableRequired

processIdinteger · int32Required

businessCaseinteger · int32Optional

productinteger · enumRequiredPossible values:

notificationEmailstringOptional

processingDatestring · date-timeOptional

runParallelbooleanOptional

Responses

200

OK

text/plainapplication/jsontext/json

post

/api/addressprocessing/Create

HTTPcURLJavaScriptPython

POST /api/addressprocessing/Create HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 226

{
  "orderNr": "text",
  "dataGroupId": 1,
  "dataGroupCode": "text",
  "userDescription": "text",
  "processId": 1,
  "businessCase": 1,
  "product": "1 = Enrich",
  "notificationEmail": "text",
  "processingDate": "2026-01-24T00:25:47.353Z",
  "runParallel": true
}

application/jsontext/jsonapplication/*+json

200

OK

{
  "batchId": 1,
  "batchUniqueId": "123e4567-e89b-12d3-a456-426614174000",
  "processGroup": 1,
  "insertBy": "text",
  "insertAt": "2026-01-24T00:25:47.353Z",
  "description": "text",
  "userDescription": "text",
  "status": "text",
  "startDate": "2026-01-24T00:25:47.353Z",
  "endDate": "2026-01-24T00:25:47.353Z",
  "processingDate": "2026-01-24T00:25:47.353Z",
  "duration": 1,
  "errorCount": 1,
  "warningCount": 1,
  "warningRejectCount": 1,
  "createTypeId": 1,
  "runSingle": true,
  "agent": "text",
  "datagroupId": 1,
  "orderNr": "text",
  "files": [
    {
      "fileUniqueId": "123e4567-e89b-12d3-a456-426614174000",
      "direction": "text",
      "fileName": "text",
      "processFileDetection": "text",
      "description": "text"
    }
  ],
  "steps": [
    {
      "stepId": 1,
      "status": "text",
      "sortOrder": 1,
      "startDate": "2026-01-24T00:25:47.353Z",
      "endDate": "2026-01-24T00:25:47.353Z",
      "duration": 1,
      "errorCount": 1,
      "warningCount": 1,
      "warningRejectCount": 1,
      "recordCount": 1,
      "description": "text",
      "modulUniqueId": "123e4567-e89b-12d3-a456-426614174000",
      "descriptionAdd": "text"
    }
  ]
}

SetBatchSettings

Setzt Batch-Einstellungen.

Request-Parameter

Erklärung

property-name

Setting Werte werden als Property im Body mit den jeweiligen Werten übergeben: InputMapping Definiert, welches Datenmapping zur Datenverarbeitung angewendet wird. RangeBack für zu betrachtende Adressänderungen (z.B. Umzüge der letzten 12 Monate). → Standardwert: 36 Monate WebhookUrl zur Automatisierung nach Abschluss des Batches. Kann zur weiteren Automatisierung von Prozessen genutzt werden, um nach Abschluss des Batches Aktionen beim Kunden auszulösen (z.B. Aktualisierung von Reports in PowerBI). webhookmethod Definiert die HTTP-Methode, die für den Aufruf verwendet wird (z. B. POST oder PUT). webhookheader Optional – definiert die HTTP-Headers als Stringified JSON, z. B. zur Übergabe von Authentifizierungstokens. webhookbody Optional – definiert den HTTP-Body als Stringified JSON, z. B. zur Übermittlung individueller Nutzdaten oder Payloads.

post

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/SetBatchSettings

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

uidstring · uuidOptional

Body

application/jsontext/jsonapplication/*+json

Other propertiesstringOptional

Responses

200

OK

text/plainapplication/jsontext/json

Responsestring

post

/api/addressprocessing/SetBatchSettings

HTTPcURLJavaScriptPython

POST /api/addressprocessing/SetBatchSettings HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "ANY_ADDITIONAL_PROPERTY": "text"
}

application/jsontext/jsonapplication/*+json

200

OK

text

FileUpload

Fügt eine Datei zur Verarbeitung hinzu.

post

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/FileUpload

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

batchIdinteger · int32Optional

batchUidstring · uuidOptional

descriptionstringOptional

Body

multipart/form-data

filestring · binaryOptional

Responses

200

OK

text/plainapplication/jsontext/json

Responsestring

post

/api/addressprocessing/FileUpload

HTTPcURLJavaScriptPython

POST /api/addressprocessing/FileUpload HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}

200

OK

text

AddRecords

Einzelne Datenrecords hochladen – unabhängig von einem FileUpload. Die Funktion kann verwendet werden, um einzelne neue Records zu übermitteln oder bestehende Uploads durch zusätzliche Records zu ergänzen.

put

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/AddRecords

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

idinteger · int32Optional

uidstring · uuidOptional

Bodyobject[]

application/jsontext/jsonapplication/*+json

customerIdstring | nullableOptional

classificationstring | nullableOptional

dwhIdstring | nullableOptional

kbbCompanyIdinteger · int32 | nullableOptional

kbcPersonIdinteger · int32 | nullableOptional

kbcHouseholdIdinteger · int32 | nullableOptional

beacinteger · int32 | nullableOptional

egidstring | nullableOptional

edidstring | nullableOptional

postAddressIdstring | nullableOptional

freetext1string | nullableOptional

freetext2string | nullableOptional

freetext3string | nullableOptional

freetext4string | nullableOptional

freetext5string | nullableOptional

firstnamestring | nullableOptional

companyNamestring | nullableOptional

namestring | nullableOptional

birthDatestring | nullableOptional

streetstring | nullableOptional

streetNostring | nullableOptional

streetAddstring | nullableOptional

careOfstring | nullableOptional

poBoxstring | nullableOptional

poZipstring | nullableOptional

poTownstring | nullableOptional

zipstring | nullableOptional

townstring | nullableOptional

mobileNostring | nullableOptional

phoneNostring | nullableOptional

emailstring | nullableOptional

uidstring | nullableOptional

chnrstring | nullableOptional

Responses

200

OK

text/plainapplication/jsontext/json

Responsestring

put

/api/addressprocessing/AddRecords

HTTPcURLJavaScriptPython

PUT /api/addressprocessing/AddRecords HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 561

[
  {
    "customerId": "text",
    "classification": "text",
    "dwhId": "text",
    "kbbCompanyId": 1,
    "kbcPersonId": 1,
    "kbcHouseholdId": 1,
    "beac": 1,
    "egid": "text",
    "edid": "text",
    "postAddressId": "text",
    "freetext1": "text",
    "freetext2": "text",
    "freetext3": "text",
    "freetext4": "text",
    "freetext5": "text",
    "firstname": "text",
    "companyName": "text",
    "name": "text",
    "birthDate": "text",
    "street": "text",
    "streetNo": "text",
    "streetAdd": "text",
    "careOf": "text",
    "poBox": "text",
    "poZip": "text",
    "poTown": "text",
    "zip": "text",
    "town": "text",
    "mobileNo": "text",
    "phoneNo": "text",
    "email": "text",
    "uid": "text",
    "chnr": "text"
  }
]

application/jsontext/jsonapplication/*+json

200

OK

text

Start

Startet die Verarbeitung.

post

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/Start

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

idinteger · int32Optional

uidstring · uuidOptional

Responses

200

OK

text/plainapplication/jsontext/json

Responsestring

post

/api/addressprocessing/Start

HTTPcURLJavaScriptPython

POST /api/addressprocessing/Start HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

text

Detail

Bietet eine Übersicht aller verfügbaren Dateien und deren Verarbeitungsschritte. Enthält zudem die eindeutige Identifikationsnummer jeder Datei.

get

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/Detail

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

idinteger · int32Optional

uidstring · uuidOptional

Responses

200

OK

text/plainapplication/jsontext/json

get

/api/addressprocessing/Detail

HTTPcURLJavaScriptPython

GET /api/addressprocessing/Detail HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "batchId": 1,
  "batchUniqueId": "123e4567-e89b-12d3-a456-426614174000",
  "processGroup": 1,
  "insertBy": "text",
  "insertAt": "2026-01-24T00:25:47.353Z",
  "description": "text",
  "userDescription": "text",
  "status": "text",
  "startDate": "2026-01-24T00:25:47.353Z",
  "endDate": "2026-01-24T00:25:47.353Z",
  "processingDate": "2026-01-24T00:25:47.353Z",
  "duration": 1,
  "errorCount": 1,
  "warningCount": 1,
  "warningRejectCount": 1,
  "createTypeId": 1,
  "runSingle": true,
  "agent": "text",
  "datagroupId": 1,
  "orderNr": "text",
  "files": [
    {
      "fileUniqueId": "123e4567-e89b-12d3-a456-426614174000",
      "direction": "text",
      "fileName": "text",
      "processFileDetection": "text",
      "description": "text"
    }
  ],
  "steps": [
    {
      "stepId": 1,
      "status": "text",
      "sortOrder": 1,
      "startDate": "2026-01-24T00:25:47.353Z",
      "endDate": "2026-01-24T00:25:47.353Z",
      "duration": 1,
      "errorCount": 1,
      "warningCount": 1,
      "warningRejectCount": 1,
      "recordCount": 1,
      "description": "text",
      "modulUniqueId": "123e4567-e89b-12d3-a456-426614174000",
      "descriptionAdd": "text"
    }
  ]
}

Files

Sämtliche Files welche von der Verarbeitung erstellt wurden und zum Downlaod bereitstehen.

get

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/Files

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

idinteger · int32Optional

uidstring · uuidOptional

Responses

200

OK

text/plainapplication/jsontext/json

get

/api/addressprocessing/Files

HTTPcURLJavaScriptPython

GET /api/addressprocessing/Files HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

[
  {
    "fileUniqueId": "123e4567-e89b-12d3-a456-426614174000",
    "direction": "text",
    "fileName": "text",
    "processFileDetection": "text",
    "description": "text"
  }
]

FileDownload

Lädt verarbeitete Dateien herunter.

get

https://webservices.kbdata.chhttps://webservices-dev.kbdata.ch

/api/addressprocessing/FileDownload

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

idinteger · int32Optional

uidstring · uuidOptional

decompressbooleanOptionalDefault: false

Responses

200

OK

No content

get

/api/addressprocessing/FileDownload

HTTPcURLJavaScriptPython

GET /api/addressprocessing/FileDownload HTTP/1.1
Host: webservices.kbdata.ch
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

No content

Webhooks

Die Batch bietet Webhooks an, um automatisierte Benachrichtigungen nach abgeschlossenen Prozessen zu ermöglichen. Sie können eingerichtet werden, um nach der Verarbeitung eines Batches eine Benachrichtigung auszulösen.

Konfiguration des Webhooks

Details zur Einrichtung finden Sie unter SetBatchSettings.

WebhookUrl

• Ermöglicht die Automatisierung von Prozessen nach Abschluss eines Batches.

• Unterstützt aktuell GET-Requests mit Querystring-Parametern.

Unterstützte Events

• Batch abgeschlossen: Benachrichtigung, sobald die Verarbeitung eines Batches abgeschlossen ist.