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.
$ 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/scores.write sonde-platform/questionnaires.read sonde-platform/questionnaire-responses.write sonde-platform/questionnaire.write'
Response1:
{ "access_token": "ya29.QQIBibTwvKkE39hY8mdkT_mXZoRh7Ub9cK9hNsqrxem4QJ6sQa36VHfyuBe", "expire_in": 3600, "token_type": "Bearer" }
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.
$ curl --request POST 'https://api.sondeservices.com/platform/v2/users' \ --header 'Authorization: <access_token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "yearOfBirth": "1985", "gender": "Female", "language": "HINDI", "device": { "type": "MOBILE", "manufacturer": "VIVO" } }'
Response2:
Capture the userIdentifier
, in the below response wiNODNXcm
.
{ "requestId": "23454556", "userIdentifier": "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.
$ curl --request POST 'https://api.sondeservices.com/platform/v1/questionnaires' \ --header 'Authorization: <access_token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "title": "covid_19", "language": "en", "questions": [ { "type": "MULTIPLE_CHOICE", "text": "Have you been within 6 feet of a person with a lab confirmed case of COVID-19 or with symptoms of COVID-19 for at least 15 minutes, or had direct contact with their mucus or saliva,in the past 14 days?", "isSkippable": false, "options": [ { "text": "No", "score": 0 }, { "text": "Yes", "score": 1 } ] }, { "type": "MULTIPLE_SELECT", "text": "In the last 48 hours, have you had any of the following NEW symptoms? Select all that apply.", "isSkippable": false, "options": [ { "text": "Fever of 100.4° F or above", "score": 3 }, { "text": "Cough", "score": 2 }, { "text": "Trouble breathing", "score": 1 }, { "text": "None of the above", "score": 0 } ] }, { "type": "TEXT_FIELD", "text": "How many covid center do you have in your city?", "isSkippable": true, "inputDataType": "INTEGER" }, { "type": "TEXT_FIELD", "text": "What is your text temperature?", "isSkippable": true, "inputDataType": "BODY_TEMPERATURE" } ] }'
Response3:
{ "id": "qnr-c79f28329", "language": "en", "requestId": "ab3e2522-d3ca-4991-a9f5-faa66371b214" }
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.
curl --request GET 'https://api.sondeservices.com/platform/v1/questionnaires/<questionnaireId>?language=<language>' \ --header 'Authorization:<access_token>'
Response4:
{ "id": "qnr-c79f28329", "title": "covid_19", "language": "en", "questions": [ { "type": "MULTIPLE_CHOICE", "text": "Have you been within 6 feet of a person with a lab confirmed case of COVID-19 or with symptoms of COVID-19 for at least 15 minutes, or had direct contact with their mucus or saliva,in the past 14 days?", "isSkippable": false, "options": [ { "text": "No", "score": 0 }, { "text": "Yes", "score": 1 } ] }, { "type": "MULTIPLE_SELECT", "text": "In the last 48 hours, have you had any of the following NEW symptoms? Select all that apply.", "isSkippable": false, "options": [ { "text": "Fever of 100.4° F or above", "score": 3 }, { "text": "Cough", "score": 2 }, { "text": "Trouble breathing", "score": 1 }, { "text": "None of the above", "score": 0 } ] }, { "type": "TEXT_FIELD", "text": "How many covid center do you have in your city?", "isSkippable": true, "inputDataType": "INTEGER" }, { "type": "TEXT_FIELD", "text": "What is your body temperature?", "isSkippable": true, "inputDataType": "BODY_TEMPERATURE" } ], "requestId": "726a8184-639c-41ed-9de7-ac7b2e79f312" }
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.
$ curl --request POST 'https://api.sondeservices.com/platform/v1/questionnaire-responses' \ --header 'Content-Type: application/json' \ --header 'Authorization: <access_token>' \ --data-raw '{ "questionnaire": { "id": "<qid>", "language": "en", "userIdentifier":"<subjectIdentifier>", "respondedAt": "1994-11-05T13:15:30Z", "questionResponses": [ { "optionIndex": 1 }, { "optionIndexes": [1] }, { "response": 4 }, { "isSkipped": true } ] } }'
Response5:
{ "id": "qrs_21397202f07e", "requestId": "a6964f06-e174-4d60-a268-2f68df8e0e07" }