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"
}