Sonde Health API Platform Documentation

Partner Questionnaire Creation

Overview

The following use-cases (with curl language examples) are a guide for your app development. To create and consume questionnaire for a user.

Notes:

  • To access create Questionnaire Api, please contact Sonde at support@sondehealth.com. Please provide your company name and address.

API Credentials

For all use-cases, you should have the following information (the following values are examples only):

Refer Account for detail on how to create an account with Sonde and obtained below client-id & client-secret.

client-id: 6lpo5bolnp4uda4n2is3u8tt2

client-secret: 1114assc3pnln1b2lngjjml6mkce3uw0q70mrv9pqphusfbgtq9a

domain: api.sondeservices.com

The Sonde Service API uses an access-token to authenticate requests. Generate an access-token using ‘client-credential’ (consists of “client-id” and “client-secret”).

Your 'client-credential' must be kept secure on your server (or preferably in secret storage at the server-side). Do not share your client-credential in publicly accessible areas (such as GitHub, client-side code, and so forth).

Obtain the access-token by following the steps below.

API call

curl --request POST 'https://api.sondeservices.com/platform/v1/oauth2/token' \ --header 'Authorization: Basic <Base64EncodedString>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=sonde-platform/users.write sonde-platform/questionnaires.read sonde-platform/questionnaires.write sonde-platform/questionnaire-responses.read sonde-platform/questionnaire-responses.write'

Get <Base64EncodedString> using the below command

$ echo -n "<clientid>:<clientsecret>" | openssl base64 -A

API response

{ "access_token": "ya29.QQIBibTwvKkE39hY8mdkT_mXZoRh7Ub9cK9hNsqrxem4QJ6sQa36VHfyuBe", "expire_in": 3600, "token_type": "Bearer" }

Pass the “access_token” key value in the Authorization header of Sonde Service APIs.

The access_token will expire_in 3600 seconds.

The token_type is “Bearer” (this value is fixed).

For a list of supported scopes, please check the schema in the Authentication section of the API Documentation REST API Reference.

For a list of scopes required for Scoring refer to Authentication Scopes

Using the generated access-token, you can access Sonde Platform’s Services.

For example; if you want your device to submit a questionnaire to the Sonde Platform using Questionnaire Service, then you can share an access-token with the device having scope sonde-platform/questionnaire.write to restrict the access and prevent the misuse of privileges your client-credential is carrying.

As a developer, I want to register a questionnaire to consume it in my app.

On your backend perform the below steps create questionnaire and submit response.

STEP 1 : GET THE APPROPRIATE ACCESS-TOKEN
STEP 2: REGISTER A USER WITH SONDE HEALTH
STEP 3: CREATE QUESTIONNAIRE
STEP 4: GET QUESTIONNAIRE ON YOUR APP
STEP 5: SUBMIT QUESTIONNAIRE RESPONSE TO SERVER
 

Detailed explanation with curl examples of each step is given below.

STEP 1: GET THE APPROPRIATE ACCESS-TOKEN

Get the access-token with scopes sonde-platform/questionnaire.write and sonde-platform/users.write .

Ensure your client-credentials are granted to these scopes during the registration/onboarding process with Sonde Health.

 

Response1:

 

STEP 2: REGISTER A USER WITH SONDE HEALTH

Use "access_token" to register a user. Put the value of access_token into the Authorization header (refer to the below curl command).

It is expected that your server will register the user with SondePlatform during the user sign-up process.

Replace <access_token> with the value of the access_token attribute of Response1.

 

Response2:

Capture the userIdentifier, in the below response wiNODNXcm.

Keep userIdentifier in your UserManagement module (or database) to later use it for the same patient.
userIdentifier will be used in STEP 3 & STEP 6.

 

STEP 3: CREATE QUESTIONNAIRE

Call the Post questionnaires API to check the questionnaire required for measure and list of languages in which questionnaire is available on API Platform.

Response3:

questionnaire.id and questionnaire.languages are required in STEP 4.

STEP 4: GET QUESTIONNAIRE ON YOUR APP

Call /questionnaires/{questionnaireId}?language=<language> to get questionnaire.

Below API will return questionnaire qnr_67rerf432 in the English language. 

Replace <access_token> with the value of the access_token attribute from Response1.
Replace <questionnaireId> with the value of questionnaire.id attribute from Response3.
Replace <language> with en.

Response4:

 

STEP 5: SUBMIT QUESTIONNAIRE RESPONSE TO SERVER

Ask your questionnaire (received in STEP 4) to your app user and use API POST /questionnaire-responses to submit a response to the server

Replace <access_token> with the value of the access_token attribute of Response1.
Replace <questionnaireId> with the value of the id attribute of Response4.
Replace <language> with the value of the language attribute of Response4.
Replace <userIdentifier> with the value of userIdentifier attribute of Response2.

 

Fill up the questionnaire.questionResponses as per user responses for the PHQ2.

 Response5:

 

Sonde Health