# Validate & Update ## Adressprocessing Ablauf Der Batch-Prozess besteht aus den folgenden Schritten: {% stepper %} {% step %} :inbox-full: [Erstellung eines Batches](#create) {% endstep %} {% step %} Daten bereitstellen * :file-circle-plus: [Variante A – AddRecords](#addrecords) * :upload: [Variante B – FileUpload](#fileupload) {% endstep %} {% step %} :play: [Start der Verarbeitung](#start) {% endstep %} {% step %} Download der Ergebnisse * :memo-circle-check: [Variante A – GetRecords](#getrecords) * :download: [Variante B – FileDownload](#filedownload) {% endstep %} {% endstepper %} ## Funktionen ### :inbox-full: Create Ein Batch ist die Hülle, die als Rahmen für die Verarbeitung dient. Für jeden Adresslauf muss ein neuer Batch erstellt werden.
Request-ParameterErklärung
orderNrBenutzerdefinierte Referenznummer, die zur eindeutigen Identifikation einer Bestellung vergeben werden kann, z. B. für spätere Rückfragen oder Abklärungen.
dataGroupCode

Eindeutige Identifikation der Data Group.

→ Wird bei der Erstellung der Data Group (/dataGroups/create) generiert. Muss hier referenziert werden.

userDescriptionName der Kampagne oder des Batches.
processId

Systemseitig vergebene ID für den Prozess.

→ Standardwert: 400

processingDateDefiniert, wann der Batch gestartet werden soll (z.B. Batch heute erstellen, Verarbeitung am Wochenende).
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.
notificationEmailE-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 /addressprocessing/Create > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}},"schemas":{"BatchCreateRequest":{"required":["orderNr","userDescription","processId","product"],"type":"object","properties":{"orderNr":{"type":"string"},"dataGroupId":{"type":"integer","format":"int32"},"dataGroupCode":{"type":"string","nullable":true},"userDescription":{"type":"string","nullable":true},"processId":{"type":"integer","format":"int32"},"businessCase":{"type":"integer","format":"int32"},"product":{"$ref":"#/components/schemas/ProductCase"},"notificationEmail":{"type":"string"},"processingDate":{"type":"string","format":"date-time"},"runParallel":{"type":"boolean"},"settings":{"type":"object","additionalProperties":{"type":"string"}}}},"ProductCase":{"enum":["1 = Enrich","2 = Reference","3 = AddressUpdate"],"type":"string","description":"**Allowed values:**\n- `1` = `Enrich`\n- `2` = `Reference`\n- `3` = `AddressUpdate`"},"BatchDetail":{"type":"object","properties":{"batchId":{"type":"integer","format":"int32"},"batchUniqueId":{"type":"string","format":"uuid"},"processGroup":{"type":"integer","format":"int32"},"insertBy":{"type":"string","nullable":true},"insertAt":{"type":"string","format":"date-time","nullable":true},"description":{"type":"string","nullable":true},"userDescription":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"processingDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"errorCount":{"type":"integer","format":"int32","nullable":true},"warningCount":{"type":"integer","format":"int32","nullable":true},"warningRejectCount":{"type":"integer","format":"int32","nullable":true},"createTypeId":{"type":"integer","format":"int32"},"runSingle":{"type":"boolean","nullable":true},"agent":{"type":"string","nullable":true},"datagroupId":{"type":"integer","format":"int32","nullable":true},"orderNr":{"type":"string","nullable":true},"settings":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"files":{"type":"array","items":{"$ref":"#/components/schemas/BatchFile"}},"steps":{"type":"array","items":{"$ref":"#/components/schemas/BatchStep"}}}},"BatchFile":{"type":"object","properties":{"fileUniqueId":{"type":"string","format":"uuid"},"direction":{"type":"string","nullable":true},"fileName":{"type":"string","nullable":true},"processFileDetection":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"s3Key":{"type":"string","nullable":true}}},"BatchStep":{"type":"object","properties":{"stepId":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true},"sortOrder":{"type":"integer","format":"int32","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"errorCount":{"type":"integer","format":"int32","nullable":true},"warningCount":{"type":"integer","format":"int32","nullable":true},"warningRejectCount":{"type":"integer","format":"int32","nullable":true},"recordCount":{"type":"integer","format":"int32","nullable":true},"description":{"type":"string","nullable":true},"modulUniqueId":{"type":"string","format":"uuid","nullable":true},"descriptionAdd":{"type":"string","nullable":true}}}}},"paths":{"/addressprocessing/Create":{"post":{"tags":["Batch"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCreateRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/BatchCreateRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/BatchCreateRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/BatchDetail"}},"application/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}},"text/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}}}}}}}}} ``` ### :file-circle-plus: 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 /addressprocessing/AddRecords > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}},"schemas":{"BatchProcessingApiRecord":{"type":"object","properties":{"customerId":{"type":"string","nullable":true},"classification":{"type":"string","nullable":true},"dwhId":{"type":"string","nullable":true},"kbbCompanyId":{"type":"integer","format":"int32","nullable":true},"kbcPersonId":{"type":"integer","format":"int32","nullable":true},"kbcHouseholdId":{"type":"integer","format":"int32","nullable":true},"beac":{"type":"integer","format":"int32","nullable":true},"egid":{"type":"string","nullable":true},"edid":{"type":"string","nullable":true},"postAddressId":{"type":"string","nullable":true},"freetext1":{"type":"string","nullable":true},"freetext2":{"type":"string","nullable":true},"freetext3":{"type":"string","nullable":true},"freetext4":{"type":"string","nullable":true},"freetext5":{"type":"string","nullable":true},"firstname":{"type":"string","nullable":true},"companyName":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"birthDate":{"type":"string","nullable":true},"street":{"type":"string","nullable":true},"streetNo":{"type":"string","nullable":true},"streetAdd":{"type":"string","nullable":true},"careOf":{"type":"string","nullable":true},"poBox":{"type":"string","nullable":true},"poZip":{"type":"string","nullable":true},"poTown":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"town":{"type":"string","nullable":true},"mobileNo":{"type":"string","nullable":true},"phoneNo":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"uid":{"type":"string","nullable":true},"chnr":{"type":"string","nullable":true}}}}},"paths":{"/addressprocessing/AddRecords":{"put":{"tags":["Batch"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BatchProcessingApiRecord"}}},"text/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BatchProcessingApiRecord"}}},"application/*+json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BatchProcessingApiRecord"}}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ``` ### :upload: FileUpload Fügt eine Datei zur Verarbeitung hinzu. ## POST /addressprocessing/FileUpload > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/FileUpload":{"post":{"tags":["Batch"],"parameters":[{"name":"batchId","in":"query","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"batchUid","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"description","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ``` ### :play: Start Startet die Verarbeitung. ## POST /addressprocessing/Start > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/Start":{"post":{"tags":["Batch"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ``` ### :memo-circle-check: GetRecords Ruft die Resultate eines AdressProcessing-Batches direkt als **JSON** ab. Dieser Endpoint eignet sich, wenn die Daten unmittelbar im System weiterverarbeitet werden sollen, ohne eine Datei herunterzuladen. ## GET /addressprocessing/GetRecords > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/GetRecords":{"get":{"tags":["Batch"],"parameters":[{"name":"uid","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"file","in":"query","description":"Optional.","schema":{"type":"boolean","default":false}},{"name":"fileDecompress","in":"query","description":"Optional.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK"}}}}}} ``` ### :download: FileDownload Lädt die Resultate eines AdressProcessing-Batches als Datei herunter. Die Ausgabe erfolgt im **TSV-Format** (tabulatorgetrennte Werte). Über den Parameter **compressed** kann gesteuert werden, ob die Datei **komprimiert** **(.txt.gz)** (false) oder **unkomprimiert (.txt)** (true) ausgeliefert wird. ## GET /addressprocessing/FileDownload > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/FileDownload":{"get":{"tags":["Batch"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"decompress","in":"query","description":"Optional.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK"}}}}}} ``` ## Optionale Schritte (für erweiterte Anwendungsfälle) ### Detail Bietet eine Übersicht aller verfügbaren Dateien und deren Verarbeitungsschritte. Enthält zudem die eindeutige Identifikationsnummer (`fileUniqueId`) jeder Datei. #### Batch Status
Status IDNameBeschreibung
0CreatedAngelegt, noch nicht bearbeitet
1ExecuteEingereiht; sobald Ressourcen verfügbar sind, startet die Verarbeitung
2ProcessingVerarbeitung läuft
3Marked for processingÜbergangsstatus zwischen Execute und Processing
4DoneVerarbeitung erfolgreich abgeschlossen
6ErrorVerarbeitung fehlgeschlagen; es ist ein Fehler aufgetreten
8Skippedeinzelne Module wurden übersprungen
## GET /addressprocessing/Detail > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}},"schemas":{"BatchDetail":{"type":"object","properties":{"batchId":{"type":"integer","format":"int32"},"batchUniqueId":{"type":"string","format":"uuid"},"processGroup":{"type":"integer","format":"int32"},"insertBy":{"type":"string","nullable":true},"insertAt":{"type":"string","format":"date-time","nullable":true},"description":{"type":"string","nullable":true},"userDescription":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"processingDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"errorCount":{"type":"integer","format":"int32","nullable":true},"warningCount":{"type":"integer","format":"int32","nullable":true},"warningRejectCount":{"type":"integer","format":"int32","nullable":true},"createTypeId":{"type":"integer","format":"int32"},"runSingle":{"type":"boolean","nullable":true},"agent":{"type":"string","nullable":true},"datagroupId":{"type":"integer","format":"int32","nullable":true},"orderNr":{"type":"string","nullable":true},"settings":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"files":{"type":"array","items":{"$ref":"#/components/schemas/BatchFile"}},"steps":{"type":"array","items":{"$ref":"#/components/schemas/BatchStep"}}}},"BatchFile":{"type":"object","properties":{"fileUniqueId":{"type":"string","format":"uuid"},"direction":{"type":"string","nullable":true},"fileName":{"type":"string","nullable":true},"processFileDetection":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"s3Key":{"type":"string","nullable":true}}},"BatchStep":{"type":"object","properties":{"stepId":{"type":"integer","format":"int32"},"status":{"type":"string","nullable":true},"sortOrder":{"type":"integer","format":"int32","nullable":true},"startDate":{"type":"string","format":"date-time","nullable":true},"endDate":{"type":"string","format":"date-time","nullable":true},"duration":{"type":"integer","format":"int32","nullable":true},"errorCount":{"type":"integer","format":"int32","nullable":true},"warningCount":{"type":"integer","format":"int32","nullable":true},"warningRejectCount":{"type":"integer","format":"int32","nullable":true},"recordCount":{"type":"integer","format":"int32","nullable":true},"description":{"type":"string","nullable":true},"modulUniqueId":{"type":"string","format":"uuid","nullable":true},"descriptionAdd":{"type":"string","nullable":true}}}}},"paths":{"/addressprocessing/Detail":{"get":{"tags":["Batch"],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/BatchDetail"}},"application/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}},"text/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}}}}}}}}} ``` ### AddDatagroup Fügt eine Datengruppe hinzu. Daten werden in sogenannten Data Groups organisiert. Diese dienen dazu, Datensätze bei Bedarf logisch zu trennen. So lassen sich zum Beispiel Bestandskunden, Neukunden oder Kampagnen getrennt verarbeiten und auswerten. In vielen Fällen genügt jedoch auch eine einzelne Data Group, in die alle Daten geladen und fortlaufend aktualisiert werden. > Hinweis: Sobald eine Data Group gestartet wird, werden die bestehenden Daten in dieser Gruppe überschrieben. ## PUT /addressprocessing/AddDatagroup > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/AddDatagroup":{"put":{"tags":["Batch"],"parameters":[{"name":"description","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}} ``` ### GetDataGroups Listet die verfügbaren Datengruppen auf. ## GET /addressprocessing/GetDatagroups > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/GetDatagroups":{"get":{"tags":["Batch"],"parameters":[{"name":"loadAll","in":"query","required":true,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK"}}}}}} ``` ### SetBatchSettings Setzt Batch-Einstellungen.
Request-ParameterErklä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 /addressprocessing/SetBatchSettings > ```json {"openapi":"3.0.1","info":{"title":"multisource•api","version":"v2"},"tags":[{"name":"Batch"}],"servers":[{"url":"https://api.multisource.ch/v2","description":"Production - v2"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints.","name":"auth-key","in":"header"}}},"paths":{"/addressprocessing/SetBatchSettings":{"post":{"tags":["Batch"],"parameters":[{"name":"uid","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}},"text/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}},"application/*+json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://multisource.gitbook.io/multisource-api/integration/validate-and-update.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.