# Validate & Update ## Address Processing Workflow The batch process consists of the following steps: {% stepper %} {% step %} :inbox-full: [Create a Batch](#create) {% endstep %} {% step %} Upload File and Start Batch * :upload: [Variant A – File upload](#fileupload) * :file-circle-plus: [Variant B – Add records](#addrecords) {% endstep %} {% step %} :play: [Start processing](#start) {% endstep %} {% step %} :magnifying-glass: [Retrieve details](#detail) {% endstep %} {% step %} Download results * :download: [Variant A – File download](#filedownload) * :memo-circle-check: [Variant B – Retrieve records](#getrecords) {% endstep %} {% endstepper %} ## Functions ### :inbox-full: Create A batch serves as the container that defines the processing frame. A new batch must be created for each address run.
Request-Parameter
orderNrCustom reference number that can be assigned for the unique identification of an order, e.g., for later inquiries or clarifications.
dataGroupCode

Unique identification of the Data Group.

→ Generated during the creation of the Data Group (/dataGroups/create). Must be referenced here.

userDescriptionName of the campaign or batch.
processId

System-assigned ID for the process.

→ Default value: 400

processingDateDefines when the batch should be started (e.g., create the batch today, process over the weekend).
businessCase

Defines the process flow based on predefined presets.

→ Default value: 0

product

Selection of the desired product, e.g.:

  • 1 Enrich: Enrich existing data.
  • 2 Reference: Only analyze the data against available data sources, no data changes → Result: Analysis report from multisource and, if applicable, from Swiss Post.
  • 3 AddressUpdate: Update existing addresses.
notificationEmailEmail address for notifications. If no specific email address is provided, the default email address of the currently logged-in user will be used.
## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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":"integer"},"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}}},"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"}}}}}}}}} ``` ### :upload: FileUpload Adds a file for processing. ## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"security":[{"auth-key":[]}],"components":{"securitySchemes":{"auth-key":{"type":"apiKey","description":"API Key required for authorized endpoints","name":"auth-key","in":"header"}},"schemas":{"IFormFile":{"type":"string","format":"binary"}}},"paths":{"/addressprocessing/FileUpload":{"post":{"tags":["Batch"],"parameters":[{"name":"batchId","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"batchUid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"description","in":"query","schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"$ref":"#/components/schemas/IFormFile"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"string"}},"text/json":{"schema":{"type":"string"}}}}}}}}} ``` ### :file-circle-plus: AddRecords This function can be used to upload new records individually or to supplement an existing upload with additional records. ## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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","schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","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"}}}}}}}}} ``` ### :play: Start Starts the processing. ## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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","schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","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"}}}}}}}}} ``` ### :magnifying-glass: Detail Provides an overview of all available files and their processing steps. It also includes the unique identification number (`fileUniqueId`) for each file. #### Batch Status
Status IDNameDescription
0CreatedCreated, not yet processed
1ExecuteQueued; processing starts once resources are available
2ProcessingProcessing in progress
3Marked for processingIntermediate state between Execute and Processing
4DoneSuccessfully completed
6ErrorAn error occurred during processing
8SkippedCertain modules were skipped
## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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}}},"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","schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","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"}}}}}}}}} ``` ### :download: FileDownload Downloads the results of an AdressProcessing batch as a file. The output is provided in **TSV format** (tab-separated values). The parameter **compressed** controls whether the file is delivered **compressed (.txt.gz)** (false) or **uncompressed (.txt)** (true). ## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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","schema":{"type":"integer","format":"int32"}},{"name":"uid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"decompress","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK"}}}}}} ``` ### :memo-circle-check: GetRecords Retrieves the results of an AdressProcessing batch directly as **JSON**. This endpoint is useful if the data should be processed directly within the system without downloading a file. ## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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","schema":{"type":"string","format":"uuid"}},{"name":"file","in":"query","schema":{"type":"boolean","default":false}},{"name":"fileDecompress","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK"}}}}}} ``` ## Optional Steps (for Advanced Use Cases) ### AddDatagroup Adds a data group. Les données sont organisées en Data Groups. Celles-ci permettent, si nécessaire, de séparer logiquement les enregistrements. Vous pouvez ainsi traiter et analyser séparément, par exemple, les clients existants, les nouveaux clients ou les campagnes. Dans de nombreux cas, une seule Data Group suffit : les données y sont simplement chargées et mises à jour en continu. > Remarque : Dès qu’une Data Group est lancée, les données existantes dans ce groupe sont remplacées. ## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}} ``` ### GetDataGroups Lists the available data groups. ## 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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"],"responses":{"200":{"description":"OK"}}}}}} ``` ### SetBatchSettings Sets batch settings.
Request-Parameter
property-name

Setting values

  • InputMapping Defines which data mapping will be applied to data processing.
  • RangeBack For address changes to be considered (e.g., moves from the last 12 months). → Default value: 36 months.
  • WebhookUrl For automation after the batch completion (currently only as a GET request with query string parameters). Can be used for further process automation to trigger actions for the customer after the batch completion (e.g., updating reports in PowerBI).
  • webhookmethod Defines the HTTP method to be used for the call (e.g., POST or PUT).
  • webhookheader Optional – defines the HTTP headers as a stringified JSON object, e.g. for passing authentication tokens.
  • webhookbody Optional – defines the HTTP body as a stringified JSON object, e.g. for transmitting custom data or 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"},{"url":"https://api.multisource.ch","description":"Production"},{"url":"https://apitep.multisource.ch","description":"Pre-Production Testing"}],"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","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"}}}}}}}}} ```