^{Web service integration}

Which data can be requested via the ZSR web service?

The modules to which the customer has subscribed thus determine which data can be requested. See Subscription options

Do inactive (suspended) numbers get delivered via the ZSR Webservice? 

The ZSR Webservice delivers suspended ZSR numbers as well as K numbers, provided that the suspension occurred no more than 10 years ago. 
A suspended service provider or employee can be identified as follows: at the time of the query, no valid validityPeriod exists.

Are deleted numbers delivered via the web service?

Numbers are deleted if they were issued in error and were never valid, or if they were suspended more than 10 years ago (see Suspended Numbers).

Integrators are advised to use the following procedure to identify deleted numbers:

• Load all numbers via the Numbers endpoint with no value in `modifiedFrom`, an offset of 0, and a limit of 150,000. The list contains all published numbers minus the deleted numbers.
• Compare the output with the numbers maintained in your own system. Any number present in your system but not included in the output must be treated as deleted.

Why do I not receive a response for a requested number? 

If a number is queried and no values are returned, the number is: 

• not available at santéservices ag. 
• cancelled because it was created in error. This means it was never professionally valid. 
• archived. A number is archived 10 years after deactivation.

What does the data model of the ZSR Webservice look like?

The most important entities are: 

• CareProvider 
• CareProviderBusiness   
• ClearingNumber
• EmployeeNumber   

Main entities of a ClearingNumber (Clearing Number): 

• number   
• correspondenceParty (correspondence address) 
• clearingNumberSuffix (number range = last two digits of a ZSR number) 
• account (the bank account) 
• clearingNumberLaws 
• careProvider
  • careProviderParties (addresses) 
  • qualifications 
  • employeeNumbers
• careProviderBusinesses (business locations) 
  • careProviderBusinessParties (addresses) 
  • facilities   
  • healthServices (methods)   
  • affiliations (an affiliation in an organisation) 
• businessScope (the business scope devided into parent business scope and sub business scope) 
• businessActivity 
• relatedClearingNumbers   
• relatedEmployees
• licenses 
• admissions 
• validityPeriods  

Notes: 
This is a highly simplified representation — for details, please refer to the Swagger schema. 

Which response format does the ZSR web service use?

Data are delivered in JSON format (XML is not supported).

Can reference data (master data) be loaded separately?

Reference/master data for ZSR/K number values (methods, qualifications, banks etc.) do not have to be loaded separately. All required data are delivered directly in the detailed response for the individual number.

If needed, reference/master data can be entered separately as follows:

• All enum values (e.g. gender, canton etc.) are already contained in full in swagger.json (JSON). The Swagger Editor or other tools can be used to generate ZSR web service reference classes automatically, complete with the corresponding enum values.
• The following values are not contained in swagger.json as enum values, but they can be requested via a dedicated ZSR web service endpoint:
  • Affiliations (association codes)
  • BusinessActivities
  • BusinessScopes (partner type groups/sub-groups)
  • CareProviderCertification
  • ClearingNumberSuffixes (number groups)
  • Countries
  • Distribution Types
  • Facilities (location features)
  • FunctionalUnits
  • HealthServices (methods)
  • Qualifications

Unique identification of the reference data is possible using the element “key” (string). See Are technical IDs delivered?

Example: "key": "3fa85f64-5717-4562-b3fc-2c963f66afa6"

Where can I find the technical API documentation?

An Open API Specification is available. In addition to Swagger, (for example) ReDoc can be used to display the open API specification.

Swagger: 
The Swagger UI allows individual queries to be tested. However, the representation in Swagger is not exhaustive with regard to property display of multiply inherited entities, meaning not all properties of entities are displayed in the Swagger UI. 

Redocly: 
As an alternative GUI, Redocly is provided in addition to Swagger UI. JSON entities are always displayed with all properties. The JSON view can be accessed under /ApiGateway/docs: 
Live system: https://zsrnext.ch/ApiGateway/docs 

Is there a version history for the ZSR web service?

The ZSR web service is currently at version v1.x. For the time being, all changes to the ZSR web service will not be implemented via new versions in parallel operation but will instead be made directly in version v1.x. However, all changes will be published in release notes at the appropriate time and made available via the stage system. Thesantéservices Service Level Agreement SLAapply.

Is an integration environment available to customers?

An integration platform is available at int.zsrnext.ch/ for integrating the ZSR web service and for pre-testing new web service versions.
The integration platform's data status is updated weekly every Wednesday morning with a live copy. Due to data updates and maintenance work, interruptions to the integration platform are to be expected every Wednesday from 6:00 a.m. to 12:00 p.m.

What are the current santéservices ag IT SLAs?

The santéservices IT Service Level Agreement SLA applies to the web service.

^{Questions and support}

Where can I request access to the ZSR web service?

Please contact us to request access to the ZSR web service.

Who can provide support if I have an issue with the ZSR web service?

Please contact us.

^{Authentication and submitting requests}

How do I access the ZSR web service?

Please contact us to request access to the ZSR web service.

How does authentication work?

Authentication is based on OpenID Connect or OAuth 2.0 using password grant.

Access token

The access token response contains additional information:

{
  "access_token": "MTQ0NjOkZmQ5OTM5NDE9ZTZjNGZmZjI3",
  "refresh_token": "GEbRxBNZmQOTM0NjOkZ5NDE9ZedjnXbL",
  "token_type": "bearer",
  "expires_in": 300,
  "scope": "openid profile email offline_access roles c1s_profile cpr"
}

The token itself is a JWT and can therefore be decoded on the JWT website.

The expires_in field defines the validity period of the token in seconds. Afterwards, a new token must be retrieved.

Code samples

A complete c# sample shows how to access one specific API resource (numbers): 

<div class="references">

CprApiAccessSample.zip

</div>

Authentication in other languages follows the same procedure.

The following code snippets explain the procedure on a step-by-step basis:

        /// <summary>
        /// Loads the IAM configuration.
        /// </summary>
        private async Task<DiscoveryResponse> GetDiscoveryDocumentAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await client.GetDiscoveryDocumentAsync(new DiscoveryDocumentRequest
                {
                    Address = "[AuthorityUrl]"
                }, ct).ConfigureAwait(false);

                if (discoveryResponse.IsError)
                    throw new Exception(discoveryResponse.Error);

                return discoveryResponse;
            }
        }

        /// <summary>
        /// Gets a new token response with a username and password.
        /// </summary>
        private async Task<TokenResponse> RequestTokenAsync(CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

                var tokenResponse = await client.RequestPasswordTokenAsync(new PasswordTokenRequest
                {
                    ClientId = "[ClientId]",
                    ClientSecret = "[ClientSecret]",
                    UserName = "[UserName]",
                    Password = "[Password]",
                    Address = discoveryResponse.TokenEndpoint,
                    GrantType = OidcConstants.GrantTypes.Password,
                    Scope = string.Join(" ", _scopes),
                }, ct).ConfigureAwait(false);

                if (tokenResponse.IsError)
                    throw new Exception(tokenResponse.Error);

                return tokenResponse;
            }
        }

        /// <summary>
        /// Gets the access token by either requesting a new token or by using the refresh token of an already existing token.
        /// </summary>
        private async Task<string> GetAccessTokenAsync(CancellationToken ct)
        {
            if (_tokenResponse == null)
            {
                // Creates a new token response
                _tokenResponse = await RequestTokenAsync(ct).ConfigureAwait(false);
            }
            else
            {
                var jwtSecurityTokenHandler = new JwtSecurityTokenHandler();

                // Parses JWT access token
                var jwtSecurityToken = jwtSecurityTokenHandler.ReadToken(_tokenResponse.AccessToken) as JwtSecurityToken;

                // The access token might be valid now, but expired the very next millisecond.
                // Thus, add a reasonable reserve in minutes for the validity time comparison below.
                var comparisionCorrectionInMinutes = 1;

                // Compares the access token life time with the current time, modified by the comparison correction value.
                if (jwtSecurityToken.ValidTo < DateTime.UtcNow.AddMinutes(comparisionCorrectionInMinutes))
                {
                    // Updates the existing token response
                    _tokenResponse = await RefreshTokenAsync(_tokenResponse.RefreshToken, ct).ConfigureAwait(false);
                }
            }

            return _tokenResponse.AccessToken;
        }

        /// <summary>
        /// Gets an updated token response by using a refresh token.
        /// </summary>
        private async Task<TokenResponse> RefreshTokenAsync(string refreshToken, CancellationToken ct)
        {
            using (var client = new HttpClient())
            {
                var discoveryResponse = await GetDiscoveryDocumentAsync(ct).ConfigureAwait(false);

                var tokenResponse = await client.RequestTokenAsync(new TokenRequest
                {
                    ClientId = "[ClientId]",
                    ClientSecret = "[ClientSecret]",
                    Address = discoveryResponse.TokenEndpoint,
                    ClientCredentialStyle = ClientCredentialStyle.AuthorizationHeader,
                    GrantType = OidcConstants.GrantTypes.RefreshToken,
                    Parameters =
                    {
                        { "refresh_token", refreshToken },
                        { "scope", string.Join(" ", _scopes) }
                    }
                });

                if (tokenResponse.IsError)
                    throw new Exception(tokenResponse.Error);

                return tokenResponse;
            }
        }

        /// <summary>
        /// A simple CPR API number search request.
        /// </summary>
        private async Task<BulkResponse> CprApiSampleRequestAsync(string accessToken, CancellationToken ct)
        {
            BulkResponse bulkResponse = new BulkResponse();

            using (var client = new HttpClient())
            {
                client.SetBearerToken(accessToken);

                var response = await client.GetAsync($"https://[CprBaseUrl]/ApiGateway/api/v1/numbers?searchOptions=Okp&offset=0&limit=10", ct).ConfigureAwait(false);

                if (!response.IsSuccessStatusCode)
                    throw new Exception("There was a problem with the request");

                string content = await response.Content.ReadAsStringAsync();

                if (content != null && content.Length > 0)
                {
                    bulkResponse = JsonConvert.DeserializeObject<BulkResponse>(content);
                }
            }

            return bulkResponse;
        }

        var accessToken = await GetAccessTokenAsync(ct).ConfigureAwait(false);

        var cprApiResponse = await CprApiSampleRequestAsync(accessToken, ct).ConfigureAwait(false);

What are the limits on batch requests?

Batch requests are defined as involving more than 50 requests per minute for a given customer.
Requests from batch processes on online services provided by santéservices ag may only be carried out between 10.00 pm and 4.00 am.
santéservices ag’s online services have limits in place that cause batches of more than 1,000 requests per minute for a given customer to be rejected (http status code 503).

See also the santéservices IT Service Level Agreement SLA.

Why can I only call up 500 numbers in the detail view?

Requests involving the endpoints ClearingNumbers and EmployeeNumbers are limited to 500 numbers for performance reasons. The request process must be planned such that no request contains more than 500 numbers.

Which status codes does the web service return?

The web service uses http status codes. The following codes may be returned:

How can 503 errors be avoided?

If the API is overloaded with large numbers of parallel requests, it returns 503 errors. To avoid these, it is very important to follow the instructions for loading the number list and the number details (see also How can data on ZSR and K numbers be requested via the web service?). The number of requests can be reduced further, for example, by requesting only changes via a daily change batch request (see also How can changes be requested?). When a 503 error occurs, it is advisable to wait five minutes before making another request. If possible, customers should check whether API requests can be deferred to a time slot during the night.

How can 400 errors be avoided?

When the client sends an invalid request to the API, it returns a 400 error. To avoid these, it is very important to follow the instructions for loading the number list and the number details (see also How can data on ZSR and K numbers be requested via the web service?). The request process must be planned such that no request contains more than 500 numbers.

400 errors may also occur if the query is sent from a sender that has not been configured in the WAF (Web Application Firewall) whitelist for the relevant user. In this case, please contact us and provide the IP address (or IP range) from which the query is being made. 

^{ZSR and K number requests}

How can data on ZSR and K numbers be requested via the web service?

Data are requested in two steps.

Step 1 – Loading the number list:

Request all the required ZSR/K numbers via the Numbers endpoint. The filter criteria employed and user authorisations affect the search results. The Numbers endpoint delivers all ZSR/K numbers that match the filter criteria and for which the customer is authorised. It does not deliver ZSR/K numbers that have been suspended for more than ten years.

Filter criteria:

• filterOptions: limits the numbers returned to specific categories/certifiers. The modules available are as for the subscription options.
• numberTypes: sets the type of number returned (ZSR or K number).
• offset: paging value that skips a set number of numbers. As a rule, this can be set to 0.
• limit: paging value that limits how many numbers are returned. To ensure that all numbers can be loaded at once with a request, a relatively high value can be set here, e.g. 200,000.
• modifiedFrom: the “modified from” date; see How can changes be requested?

Step 2 – Loading the number details:

The result from step 1 is used to make a request via the appropriate detail endpoint for 500 numbers at a time.

Endpoints:

• For ZSR numbers: ClearingNumbers endpoint
  For K numbers: EmployeeNumbers endpoint

The response from the detail endpoint contains the complete number details for which the user is authorised. For performance reasons, it is important to avoid making large numbers of parallel individual requests.

Can I search for specific properties of a ClearingNumber or EployeeNumbers?

Extended search queries with filter criteria at field level, e.g. by name and postcode, are not offered via the web service. The full version of ZSR is available for advanced search queries.

How is the ClearingNumbers endpoint used?

The ClearingNumbers endpoint delivers details of ZSR numbers.

See How can data on ZSR and K numbers be requested via the web service?

How is the EmployeeNumbers endpoint used?

The EmployeeNumbers endpoint delivers details of K numbers.

See How can data on ZSR and K numbers be requested via the web service?

According to which logic are qualifications assigned? 

qualificationTitleType 
We indicate whether a qualification is federal or recognised by MEBEKO. This differentiation is possible for diplomas (qualificationGroupType "DIPLOMA") or postgraduate titles (qualificationGroupType "POSTGRADUATE_TITLE"). Private-law postgraduate titles (qualificationGroupType "PRIVATE_LAW_POSTGRADUATE_TITLE") are always federal titles. We currently use "UNKNOWN". 

Possible values:

• RECOGNIZED_MEBEKO
• FEDERAL 

qualificationGroupType 

Analogous structure according to MedReg. Division of qualifications into the types diploma, postgraduate title, and private-law postgraduate title. 

Possible values:

• DIPLOMA   
• POSTGRADUATE_TITLE
• PRIVATE_LAW_POSTGRADUATE_TITLE  

qualificationType 
Unlike qualificationGroupType, private-law postgraduate titles (PRIVATE_LAW_POSTGRADUATE_TITLE) are differentiated into certificate of competence (SIWF_CERTIFICATE) and specialisation (SIWF_SPECIALIZATION). 

Possible values: 

• DIPLOMA
• FMH_POSTGRADUATE_TITLE
• SIWF_CERTIFICATE
• SIWF_SPECIALIZATION 

Summary: 
For partner type parent groups listed in MedReg (Doctor, Pharmacist, Chiropractor, Dentist), the QualificationType corresponds to the MedReg "Private-law postgraduate type", the QualificationTitleType corresponds to the MedReg diploma/postgraduate type, and the QualificationGroupType corresponds to the MedReg classification into diploma, postgraduate title, and private-law postgraduate title. 

For all other parent groups, "Unknown" is used for QualificationGroupType and QualificationTitleType. For QualificationType, further distinctions are made depending on the parent group, such as Diploma, Certificate, Admission, LaboratoryPostgraduateTitle, LaboratorySpecialization, and OrthopedicShoeTechnologyPostgraduateTitle. 

How can changes be requested?

A “modified from” date can be set as a parameter via the Numbers endpoint. The response then contains only numbers that have been changed since that date. Modifications can be specialist in nature or concern purely technical values. Numbers that have been suspended or cancelled for more than ten years are not delivered via the Numbers endpoint. To find out which numbers are affected, all active numbers must first be loaded via the Numbers endpoint. Any numbers that are still active in the client system but are not contained in the results should be cancelled or deleted from the client system.

Once all modified numbers have been loaded, their details can be requested in the usual way via the detail endpoints. The response from these endpoints always contains all available data on a ZSR/K number, not just the values that have been changed.
Changes can be processed from the client system, e.g. by comparing the JSON result from the last request with the JSON result from the new request. The following cases must be borne in mind:

• An element with the technical ID x exists in the client system and is delivered in the JSON result: it is important to check whether a field value of the element that is relevant for the client system has changed.
• An element with the technical ID y exists in the client system and is not delivered in the JSON result: all of the element’s field values are regarded as cancelled and must be removed.
• An element with the technical ID z does not exist in the client system and is delivered in the JSON result: all of the element’s field values are new and must be entered.

The API should always be integrated such that it works regardless of the number of changes reported, i.e. threshold values set by the customer should not cause the data import to fail.

Is it possible to load only ZSR/K numbers that have been changed?

Yes. The filter criterion “modifiedFrom” makes it possible to request changes by date. See also How can changes be requested?

How are changes handled?

• An element with the technical ID x exists in the client system and is delivered in the JSON result: it is important to check whether a field value of the element that is relevant for the client system has changed.
• An element with the technical ID y exists in the client system and is not delivered in the JSON result: all of the element’s field values are regarded as cancelled and must be removed.
• An element with the technical ID z does not exist in the client system and is delivered in the JSON result: all of the element’s field values are new and must be entered.

There are thus two different ways in which a change to an existing value can be delivered:

• Option 1: with change history → an element with a new technical ID is created every time a field value is changed.
• Option 2: without change history → the technical ID remains unchanged when a field value is changed.

The final version of the web service will only use Option 1. For the time being, however, integration must ensure that the client systems can handle both options.

^{Interpreting the data}

How are ZSR number relationships delivered in the web service?

• relatedClearingNumberscontains ZSR number relationships recorded manually by santéservices. These are only kept on record until data confirmed by the service provider are available.
• ClearingNumberscontains ZSR number relationships confirmed by the service provider.
• EmployeeNumberscontains K number relationships confirmed by the service provider (these are NOT employee relationships).

To receive all ZSR number relationships, therefore, it is essential to take account of both ClearingNumber.relatedClearingNumbers and CareProvider.ClearingNumbers

    "relatedClearingNumbers": [
        {
          "clearingNumber": "B222222",
          "clearingNumberRelationType": "CHANGE_OF_HANDS",
          "clearingNumberRelationTypeTranslations": {
            "de": "Besitzerwechsel",
            "fr": "Changement de propriétaire",
            "it": "Cambiamento di proprietario"
          },
          "id": 520754
        }
      ] 

"clearingNumbers": [
          {
            "number": "N111111"
          }
        ] 

 "employeeNumbers": [
          {
            "number": "999999K"
          }
        ] 

Employee relationships are delivered under clearingNumber.relatedEmployees or in the EmployeeNumbers endpoint under employeeNumber.relatedEmployers.

What do the data items “0001-01-01” and “9999-12-31” mean?

The ZSR web service always delivers a start date and an end date for time periods, even if it is not possible to determine the exact dates due to the legacy data or for other reasons.

Placeholder values for the start and end date are therefore used. These are to be interpreted as follows:

• “0001-01-01” is a placeholder value for the start date and means that the actual start date is not known (NULL).
• “9999-12-31” is a placeholder value for the end date and means that the actual end date is not known (NULL).

A time period with the start date “0001-01-01” and the end date “9999-12-31” is thus valid for any given point in time.

Are technical IDs delivered?

Element id

The IDs delivered in the detailed response have no specialist meaning and should not be used to interpret values. They are purely technical identifiers of the delivered data and can serve to process changes (see How can changes be requested? and How are changes handled?). No logic should ever be coded to technical IDs.

In addition, no technical IDs whatsoever are delivered for the main ZSR/K number record. Identification is only possible using the ZSR/K number itself. A replacement for the old paying agent ID is not delivered.

Element key

Master/reference data, e.g. canton, country, qualification etc., are delivered with a permanent GUID as identifier. See also Can reference data (master data) be loaded separately?

Unique identification is possible using the element “key” (string) for the following entities: 

• Affiliations
• BusinessScopes
• ClearingNumberSuffixes
• Countries
• Distribution Types
• Facilities
• FunctionalUnits
• HealthServices
• Qualifications

Example: "key": "3fa85f64-5717-4562-b3fc-2c963f66afa6"

How can dummy numbers be identified?

So-called “dummy” numbers are a legacy construct. They are still in use and can be retrieved via the ZSR web service.

If a value for the property "clearingNumberDummy" is delivered on the ClearingNumber object, the number in question is a dummy number.

Example of structure:

{
	"clearingNumber": {
		"clearingNumberDummy": {
			"id": 912
			"name": "CH-Arzt",
		}
	}
}

How are partner type groups/sub-groups displayed in the web service?

All service providers apart from doctors

• The partner type group value is always delivered in the field “parentBusinessScope”.
• The partner type sub-group value, if available, is delivered in the field “businessScope”.
• Otherwise, the partner type group value is delivered.

Doctors
Doctors are categorised in terms of business scope and business activity.

The “businessScope”/”parentBusinessScope” values can be queried in the web service via the BusinessScopes endpoint: /api/v1/businessscopes.

The “businessActivity” values can be queried in the web service via the BusinessActivities endpoint: /api/v1/businessactivities.

^{General information on the paying agent register}

How is a valid number constructed?

The clearing number has the following structure:

• A leading char as check digit
• A four digit sequential number
• A two digit number circle / canton number

The leading char of the clearing number is created and validated as follows:

• Each number is multiplied with its position (calculate from the right end).
• All products are summarized into one sum.
• Modulo 26 of the sum denotes the char in the alphabet (result 0 results in char 'Z'). 

Example L248519:
(9*1)+(1*2)+(5*3)+(8*4)+(4*5)+(2*6) = 90
90 mod 26 = 12
12th char in the alphabet = L

How is a valid K number constructed?

K numbers consist of a six-digit serial number followed by the letter K.