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.