General description of S2S API

• Go here for a general description of the S2S API data submission service.

Training

• Go here to watch the S2S API training organized by healthdata.be.

API endpoint description

• Go here for an overview of API endpoints and the relevant information.

Data submission procedure in Architecture 2 using S2S API

1. Requirements at Data Provider's side

In order to be able to communicate with the healthdata.be S2S API, the IT services of the healthcare organizations must setup their systems as follows:

• Ensure to have the credentials available for the endpoint/URL for which authorization is necessary. If this is not the case, please contact our service portal: https://sciensano.service-now.com/sp.

• Ensure to have the end-to-end API process in place in order to submit data registrations in a fully automated manner.

• Ensure capability of submitted data retrieval in the local database.

2. Preparing the JSON file

• To send data to healthdata.be by S2S API, the file must be in a .json file format.

• Extract the requested data from the electronic patient files and/or other local databases.

• Map the data according to the fields and formats as described in the DCD specifications of this section and the general code lists.
• Go here for additional information on the codes and the formats used for the Author group, SSIN code, Status, "Date" - "Date:Time", Repeatable fields and Multiple choice.

Note: Below documentation contains generic example screens with the sole purpose to demonstrate how the process looks like regardless of the registry.

3. Uploading the JSON file

• The IT department of the Data Provider implements a data transmission system (e.g. Postman) to send the API queries by means of a json file. The correct endpoints for uploading of the json file can be found here.

• The URL that needs to be entered after POST (selected method for uploading) should have a syntax similar to the one below:

POST {{baseURL}}/api/dcd/payload/submit?organization-id={organizationId}&dcd-id={dcdId}&dcd-version-id={dcdVersionId}&data-src-type={dataSrcType}

• Whereby:
  • {organizationId} needs to be replaced by the id of your organization; go here for more information
  • {dcdId} needs to be replaced by a register-specific numerical value; go here for more information
    
  • <optional> {dcdVersionId} needs to be replaced by the intended version number; if not provided, the latest version of the dcd specifications is assumed; go here for more information
  • <optional> {dataSrcType} needs to be replaced by the data source type. Permitted values are API or CSV; go here for more information
    
  • a GET method URL should not contain /submit/ in the endpoint or path
  • multiple query parameters need to be connected by an ampersand (&) (see example above)

• In the Authorization tab, select “Basic Auth” in the “Auth Type” drop-down list. Subsequently, fill out the API credentials in the username and password fields.

• In Body tab, select the “raw” option from the top line and paste the content of the JSON file in the box.

• Once the request settings are completed, press the Send button to submit the records.
• After succesful submission of the data, the “Status: 202 Accepted” code will appear below the box where the data was pasted. The bottom box should return a message about the records uploaded or an error message if any.

• A 401 Unauthorized message instead indicates missing or incorrect credentials. Request the correct credentials as described above in the Requirements at Data Provider's side.

• A 400 Bad request might refer to incorrect syntax of the API query. Check the query parameters and ensure to connect multiple parameters with the ampersand (&) character.

4. Validating the JSON Upload

4.1 Validation of the S2S API Upload via the response:

Verify in the same way the request was sent, that the returned response is containing a valid Business key.

If a valid Business key has been provided, the registration upload via System 2 System API was succesful.

4.2 Validation of the S2S API via HD4DP 2.0:

Step 1: Open the HD4DP 2.0 application.

Step 2: Select the organization in the dropdown list and click on Volgende (Next).

Step 3: Fill in the username and password, that has been provided by your IT Department or Healthdata team, and click on Log in to access the HD4DP v2.0 application.

Step 4: Navigate in the menu on the left-hand side panel to the desired study program:

Step 5: Check that the uploaded registration(s) is/are displayed in the overview table:

This documentation is being updated regularly. We try to provide as correct, complete and clear as possible information on these pages. Nevertheless, if you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please create support ticket via our portal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) or send us an e-mail via support.healthdata@sciensano.be to report this documentation issue. Please, do not forget to mention the URL or web address of the page with the documentation issue. We will then adjust the documentation as soon as possible. Thank you!