synsyn web services

User navigation



Language navigation

synsyn web services

Close

synsyn web services

Technical specifications for the “Address maintenance via web service” product

Swiss Post offers you the best possible preconditions to support you professionally in your address management. Current and valid addresses are the key to staying in contact with customers.

With the “Address maintenance via web service”, you can check and update your address database directly in your systems. This helps avoid losing addresses and customers due to a change of address. Furthermore, it reduces both the number of undeliverable items and the corresponding costs.

This synsyn web service use a REST web interface provide by Swiss Post for the purposes of data exchange. This interface is available 24/7.

More product details and contact

1. Types of access to the web service

In principle, there are two ways to access the service:

1.1 Batch processing of several addresses in a file

First, a file containing input addresses is uploaded to the service. A blank file is also defined. When uploading and creating data, a token is provided in exchange. This token enables you to start the predefined configuration. When starting the configuration, another token is provided that can be used to request the processing status. Once the processing is complete, the token provided when creating the output file can be used to download the result.

The input and output structures can be configured individually during batch processing and be defined in advance with the Address Competence Center.

1.2 Individual address queries

If only individual addresses are to be checked using the service, the individual address query can be used. In this case, an address is sent to the service and the result is received as an answer.

Using the individual address query, the output structure can be defined individually together with the Address Competence Center.

2. Checking availability and connection to the service

The easiest method for checking whether the service is available is the ping method.

The request URL is: “GET /ping”

The HTTP status 200 OK is returned in response

3. Batch processing of several addresses in a file

To align multiple addresses in a file with each other, an alignment must first be structured together with the Address Competence Center. This is then stored with the web service. To start the alignment, several steps are required:

3.1 Upload data

One or more files must be transferred to the service. These can be text files with a fixed structure, text files with a variable structure with field separators and, in certain circumstances, field delimiters or Excel files in xlsx format. The files are always uploaded as a binary data stream and are stored by the service in encrypted format.

The “POST /uploadfile” method can be used to upload an “application/octet-stream” file.

The response returned is the status of the request and, if successful, a token which defines the uploaded file in the service.

{
   "UploadFileResult": {
      "FileToken": "70abdcab-3054-49f7-a3c2-4211d9239731",
      "Status": 0
   }
}

3.2 Define output files

For each output file from the alignment, a file must be created in the service. To this end, the following method is called up: “GET /createfile”

As with the upload, the response returned is a status and a file token, which can then be used to download the data.

{
   "CreateFileResult": {
      "FileToken": "12082bae-a51b-4c2e-84b4-9245a8c9abfb",
      "Status": 0
   }
}

3.3 Start processing

To start the batch alignment, the “POST/ RunBatch” request must be executed. With this request, the file tokens generated when uploading and creating the files are assigned to the corresponding placeholders in the configuration. The key is used to specify the alignment.

{
  "key": "customkey",
  "replaceItems": [
    {
      "Search": "{###INPUTFILE###}",
      "Replacement": "70abdcab-3054-49f7-a3c2-4211d9239731"
    },
    {
      "Search": "{###OUTPUTFILE###}",
      "Replacement": "12082bae-a51b-4c2e-84b4-9245a8c9abfb"
    }
  ]
}

This returns the following response with the batch token that can be used to query the status of the alignment:

{
   "RunBatchResult": {
      "BatchToken": "63aa6978-2a6e-4c34-a57a-046310d364e0",
      "SettlementId": 21888,
      "Status": 0
   }
}

3.4 Query the processing status

To query the progress of the alignment, the “GET / checkbatchstatus/{batchtoken}” request is activated in the service. In this case, the batch token returned at the start of batch run is given as a parameter.

The response contains the status of the current processing.

{
   "CheckBatchStatusResult": {
      "BatchStatus":    {
         "LastUpdateDateTime": "/Date(1491482100937+0200)/",
         "Message": "Module 'Basiskonfiguration' is Running",
         "Progress": 18,
         "RemainingTimeSeconds": 888,
         "StartDateTime": "/Date(1491482100770+0200)/",
         "TokenStatus": 3
      },
      "Status": 0
   }
}

The individual properties have the following meanings:

Property Meaning
LastUpdateDateTime Time of the last update in Microsoft date format
Message The last message returned from the processing
Progress The progress of the processing as a percentage
RemainingTimeSeconds The approximate number of seconds the alignment still has to run
StartDateTime The processing start time
TokenStatus The processing status:
0 = New
1 = Error
2 = Waiting
3 = Running
4 = Finished
5 = Failed
6 = Canceled
7 = Unknown

3.5 Download files

When the token status for the alignment is “Finished”, the data can be downloaded. To download the result of an alignment, a download request is sent with the file token returned when the output file was created. The request is as follows: “GET /downloadfile/{filetoken}”

The response returned is a binary-coded stream of the “application/octet-stream” type, which can then be stored locally.

4. Individual address queries

In the case of an individual address query, a query can be conducted using an individual address. The query key is used to define the query to be run. Both the expected structure of the input fields and the structure of the response depend on the operation queried. A sample query of first name, last name, street, house number, postcode and town is shown below. The alignment is defined using the “querykey”. If no response is returned after 10 seconds (10,000 milliseconds), the query is interrupted.

{  
   "address": {
    "Id": 123,
    "Data": [
      { "FieldType": 11,
        "FieldName": null,
        "Value": "Julien",
        "EmptyMatch": false
      },
      { "FieldType": 13,
        "FieldName": null,
        "Value": "Nyffeler",
        "EmptyMatch": false
      },
      { "FieldType": 17,
        "FieldName": null,
        "Value": "Strickstrasse",
        "EmptyMatch": false
      },
      { "FieldType": 18,
        "FieldName": null,
        "Value": "5",
        "EmptyMatch": false
      },      
      { "FieldType": 21,
        "FieldName": null,
        "Value": "8174",
        "EmptyMatch": false
      },
      { "FieldType": 23,
        "FieldName": null,
        "Value": "Stadel",
        "EmptyMatch": false
      }
    ]
  },
  "key": "querykey",
  "timeout": 10000
}

The response is structured as defined below. The fields may differ depending on the type of query.

{
"RunQueryResult":{
   "MatchResult":{
      "FieldScore": [0],
      "Results":{
         "Data":[
            {
               "EmptyMatch": false,
               "FieldName": "QSTAT",
               "FieldType": 39,
               "Value": "4"
            },
                        {
               "EmptyMatch": false,
               "FieldName": "Vorname",
               "FieldType": 0,
               "Value": "Julien"
            },
                        {
               "EmptyMatch": false,
               "FieldName": "Nachname",
               "FieldType": 2,
               "Value": "usw."
            }
            ...
         ],
         "Id": 123
      },
      "Score": 0
   },
   "SettlementId": 18600,
   "Status": 0
}

5. QSTAT / QSTAT ShortReport

The status “QSTAT” is used to make a statement about the quality of an address. 

A distinction is made between the primary and secondary status:  

For the primary status (= QSTAT), the quality of each address is clear at a glance. 

The secondary status (= ShortReport) shows in detail which part of an address has been corrected or standardized and which address parts are correct.

5.1 QSTAT

After processing by Swiss Post, the quality and topicality of each individual address is reported with one of the following “QSTAT” primary statuses:

Status 
QSTAT
Designation Description
1 Person hit Last name, first name, additional address information, street, house number and additional information, postcode, town in accordance with our reference database.
2 Household hit First names do not match our reference database but the other address information matches our reference database.
3 Company hit Name, additional address information, street, house number and additional information, postcode and town match our reference database.
4 Move A new address is available for this address following a move.
25 Death An officially published death notice is available for this address.
26 Relocation abroad An international forwarding order is available for this address.
27 Expired forwarding order An expired forwarding order is available for this address.
50 Unidentified address This address could not be checked. This could be due to: 
- Major differences in the spelling of the last name/first name and/or company name; 
- Historic address; 
- As yet invalid or false address; 
- Foreign address; 
- Missing data sets, for example with empty lines; 
- Missing data structures with amorphous field contents.
51 Unidentified building This combination of street, house number, postcode and town does not exist.

If applicable, these duplicate results will also be reported electronically for every address in addition to the address maintenance status messages:

Status
QSTAT
Designation Description Return delivery
K Header duplicate This address is found several times in the address database and features the greatest congruity with the other records of the duplicate group. - Address maintenance status message
- Status message K
- Duplicate group number
- Any standardization, correction, supplementary and/or update data
- Match probability
F Subsequent duplicate This address is found several times in the address database and features lower congruity with the other records of the duplicate group. - Address maintenance status message
- Status message F
- Duplicate group number
- Any standardization, correction, supplementary and/or update data
- Match probability

5.2 QSTAT_ShortReport

With the help of the QSTAT ShortReport, the type of result can be evaluated and the reason for an unsuccessful request can be ascertained in greater detail. The 24-digit ShortReport is constructed as follows:

Position Definition Desription
1 Company (Company_in) Company name
2 Prename (Prename_in) First name
3 Prename2 (Prename2_in) First name 2
4 Name (Name_in) Last name
5 MaidenName (MaidenName_in) Maiden name
6 AddressAddition (Addressaddition_in) Additional address information
7 coAddress (coAddress_in) c/o address
8 StreetName (Streetname_in) Street
9 HouseNo (HouseNo_in) House number
10 HouseNoAddition (HouseNoAddition_in) House number additional information
11 Floor (Floor_in) Floor number
12 ZIPCode (ZipCode_in) Postcode
13 ZIPAddition (ZIPAddition_in) Postcode additional information
14 TownName (TownName_in) Town
15 Canton (Canton_in) Canton abbreviation
16 CountryCode (CountryCode_in) Country code
17 PoBoxTerm (PoBoxTerm_in) P.O. Box designation
18 PoBoxNo (PoBoxNo_in) P.O. Box number
19 PoBoxZIP (PoBoxZIP_in) P.O. Box postcode
20 PoBoxZIPAddition (PoBoxZIPAddition_in) P.O. Box postcode additional information
21 PoBoxTownName (PoBoxTownName_in) P.O. Box town
22 Address type Address type
23 Source type Source of the information
24 Address status Additional address information
Characters Description Detailed description
- Not analysed Input content not analysed.
1 Compliance Input content checked: OK, complete compliance.
2 Hit with discrepancy Input content checked: spelling standardized, discrepancies compared to the official spelling detected (concerns abbreviations, spelling mistakes, accents, etc.), hit with discrepancy – information has not been corrected.
3 Changed Input content checked: correction of address elements or address elements identified as archive input and replaced by official designation in output (concerns alternative/foreign-language designations).
4 Supplemented Input content checked: missing information could be completed (additional house number information, canton abbreviation, etc.).
5 New information Input content checked: information concerning a move has been found for the address checked.
6 Blocked forwarding information Input content checked: blocked information concerning a move exists for the address checked. Post CH Ltd is not authorized to forward the new address.
9 Deleted Input content checked: the information concerning the address checked is no longer valid and has been deleted.
0 No hit Input content checked: no suitable information has been found in the Post CH Ltd reference data concerning the address checked.
A-Z Special Definition according to the field (e.g. address type) or special case for a specific product. 

Exemples of ShortReport:

Example: Active correct consumer address
Position of the string Concerns address element Input Reference ShortReport
1 Company - - -
2 Prename Max Max 1
3 Prename2 - - -
4 Name Muster Muster 1
5 MaidenName - - -
6 AddressAddition - - -
7 coAddress - - -
8 StreetName Dorfstrasse Dorfstrasse 1
9 HouseNo 4 4 1
10 HouseNoAddition - - -
11 Floor - - -
12 ZipCode 6010 6010 1
13 ZipAddition 0 0 1
14 TownName Kriens Kriens 1
15 Canton LU LU 1
16 CountryCode CH CH 1
17 PoBoxTerm - - -
18 PoBoxNumber - - -
19 PoBoxZip - - -
20 PoBoxAddition - - -
21 PoBoxTownName - - -
22 Address type - - A
23 Source type - - -
24 Address status - - A
QSTAT - - - 1
Example: Consumer address with active forwarding order
Position of the string Concerns address element Input Reference ShortReport
1 Company - - -
2 Prename Hans Hans 1
3 Prename2 - - -
4 Name Müller Müller 1
5 MaidenName - - -
6 AddressAddition - - 5
7 coAddress - - 5
8 StreetName Bahnhofstasse Dorfstrasse 5
9 HouseNo 16 235 5
10 HouseNoAddition - - 5
11 Floor - - 5
12 ZipCode 6004 3933 5
13 ZipAddition 0 0 5
14 TownName Luzern Staldenried 5
15 Canton - VS 5
16 CountryCode - CH 5
17 PoBoxTerm - - 5
18 PoBoxNumber - - 5
19 PoBoxZip - - 5
20 PoBoxAddition - - 5
21 PoBoxTownName - - 5
22 Address type - - A
23 Source type - - -
24 Address status - - A
QSTAT - - - 4

6. Data structure

There are no fixed data structures, either for the processing of entire files or for individual address queries. When processing entire files, it need only be agreed how data are supplied and returned when creating the alignment configuration.

In both variants, the following information is a minimum requirement:

  • Name or company
  • First name
  • Street or P.O. Box
  • House number
  • Postcode
  • Town

7. Authentication

Authentication is conducted via an HTML basic authentication. The authentication should be “pre-emptive”.

A technical user is required for authentication. To create this user, a customer login is required on www.swisspost.ch for business customers with a billing relationship.  If a customer has such a login, they can log in to the www.swisspost.ch website and create a new technical user via the Customer Center.

8. Query status messages

For every query, the service provides a status message.

Standard

0 NoError The query was successful.

Authentication

101 AuthenticationFailed Authentication failed.
102 AuthenticationUserUnknown Unknown user.
103 AuthenticationUserMissingRole The key entered is unknown.
104 AuthenticationUserNotOwner The request fidoes not belong to the user indicated during the query.

Service bridge error

201 InternalServerCallFailed An internal error has occured in the service.
202 InternalServerCall An internal error has occured in the service.
203 InternalServerCall The query lasted longer than the defined timeout.

Database error

301 DatabaseOperationFailed An error occured when accessing the database.
302 DatabaseItemNotFound An error occured when accessing the database.

Calculation error

401 SettlementCreateFailed An error occured when recording the number for calculation purposes.

Parameter error

801 TokenParameterInvalidFormatException A parameter that has been entered does not have the correct format.
802 InvalidGeoCoordinateFormat A parameter that has been entered does not have the correct format.

Unknown error

999 UnknownError Unknown error.