Overview
The following use cases (with curl language examples) are a guide for your app development. To return a questionnaire score for a user.
Notes:
To access Mental Fitness M3 Questionnaire Score, 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 to Account for detail on how to create an account with Sonde and obtain 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/scores.write sonde-platform/questionnaires.read sonde-platform/measures.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 upload a voice sample to the Sonde Platform using Storage Service, then you can share an access-token with the device having scope sonde-platform/storage.write to restrict the access and prevent the misuse of privileges your client-credential is carrying.
As a developer, I want to generate an M3 score for mental fitness.
Score Mental Fitness health condition with the Sonde Platform “M3”.
On your backend perform the below steps to get the score:
STEP 1: GET THE APPROPRIATE ACCESS-TOKEN
STEP 2: REGISTER A USER WITH SONDE HEALTH
STEP 3: LOOK FOR THE QUESTIONNAIRE REQUIRED FOR MENTAL-FITNESS
STEP 4: GET QUESTIONNAIRE FOR MENTAL-FITNESS
STEP 5: SUBMIT QUESTIONNAIRE RESPONSE TO THE SERVER
STEP 6: CREATE INFERENCE PARAMETER FOR M3 SCORE
STEP 7: ASK FOR THE EXPECTED M3 SCORE
A 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/scores.write , sonde-platform/users.write and sonde-platform/storage.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/measures.read sonde-platform/questionnaire-responses.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: LOOK FOR THE PHQ2 QUESTIONNAIRE REQUIRED TO MENTAL-FITNESS
Call the /measures/name/{measureName}?variant=v2 API to check the questionnaire required for measure and list of languages in which questionnaire is available on API Platform.
curl --request GET 'https://api.sondeservices.com/platform/v1/measures/name/mental-fitness?variant=v3' \ --header 'Authorization:<access_token>'
Response3:
{
"id": "msr_67rerf432",
"name": "mental-fitness",
"questionnaire": {
"id": "qnr_e23er432w",
"title": "M3",
"languages": [
"en"
]
}
}
questionnaire.id and questionnaire.languages are required in STEP 4.
STEP 4: GET THE M3 QUESTIONNAIRE FOR THE MENTAL-FITNESS
Call /questionnaires/{questionnaireId}?language=<language> to get questionnaire.
Below API will return questionnaire qnr_e23er432w 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:
Note: Your app should not have string matching logic on questions[].text. Sonde can edit this text.
{
"id": "qnr-8a110a405",
"title": "M3",
"language": "en",
"questions": [
{
"type": "MULTIPLE_CHOICE",
"text": "Over the last two weeks or more, have you noticed the following (for each question select the answer that best applies to you). I feel sad, down in the dumps or unhappy",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I can't concentrate or focus",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "Nothing seems to give me much pleasure",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I feel tired; have no energy",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I have had thoughts of suicide",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I have difficulty sleeping or I sleep too much",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I have lost some appetite or I am eating more",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I feel tense, anxious or can't sit still",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I feel worried or fearful",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I have attacks of anxiety or panic",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I worry about dying or losing control",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I am nervous or shaky in social situations",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I have nightmares or flashbacks",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I am jumpy or feel startled easily",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I avoid places that remind of a bad experience",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I feel dull,numb, or detached",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I can't get certain thoughts out of my mind",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I feel I must repeat certain acts or rituals",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": " I feel the need to check and recheck things",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "Have you ever noticed the following? I have more energy than usual",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I have felt unusually irritable or angry",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I have felt unusually excited,rewed up or high",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "I have needed less sleep than usual",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "Select from the option whether any or the above symptoms interferes with work or school",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "affects my relationships with friends or family",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "has led to my using other substances",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
},
{
"type": "MULTIPLE_CHOICE",
"text": "has led to my using alcohol to get by",
"isSkippable": false,
"options": [
{
"text": "Not at all",
"score": 0
},
{
"text": "Rarely",
"score": 1
},
{
"text": "Some time",
"score": 2
},
{
"text": "Often",
"score": 3
},
{
"text": "Most of the time",
"score": 4
}
]
}
],
"requestId": "3c11160b-6e50-4e75-9498-f44e5f554ad3"
}
STEP 5: SUBMIT A QUESTIONNAIRE RESPONSE TO SERVER
Ask M3 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": "<questionnaireId>",
"language": "<language>",
"userIdentifier": "<userIdentifier>",
"respondedAt": "2020-08-17T07:11:02Z",
"questionResponses": [
{
"optionIndex": 1
},
{
"optionIndex": 0
}
]
}
}'
Response5:
Copy id attribute’s value. It is required in STEP 6.
{
"id": "qrs_09d24ef60e73"
"requestId": "23454556",
}
STEP 6: CREATE INFERENCE PARAMETER FOR M3 SCORE
Call /platform/v2/inference/inference-parameters to create InferenceParameter resource.
This API will return an inference-parameters resource’s id if validation applicable for the given measure is passed.
This API performs the below validation on the input questionnaire response id.
It should be available on Server
It should be questionnaire responses for the M3 questionnaire
Note: Your app should gracefully handle any extra validation which may be added in future releases of the Sonde API Platform.
Replace <questionnaireResponseId> with the value of id attribute of Response5.
$ curl --request POST 'https://api.sondeservices.com/platform/v2/inference/inference-parameters' \
--header 'Content-Type: application/json' \
--header 'Authorization: <access_token>' \
--data-raw '{
"infer": "QuestionnaireScore",
"parameter": {
"measure": {
"name": "mental-fitness",
"variant": "v3"
},
"questionnaireResponse": {
"id": "<questionnaireResponseId>"
}
}
}'
Response6:
{
"requestId": "f63d575a-f4d1-4343-9544-b96b1ac16b38",
"questionnaireResponse": "qrs_644596b20363",
"id": "inp_8e01f3adf",
"type": "QuestionnaireScoreInferenceParameter"
}
id is required in STEP 7.
STEP 7: ASK FOR THE EXPECTED M3 SCORE
Call the /v2/inference/scores API to trigger M3 score processing. Refer to the below curl command.
Replace <inferenceParameterId> with the value of id attribute of Response6.
$ curl --request POST 'https://api.sondeservices.com/platform/v2/inference/scores' \
--header 'Content-Type: application/json' \
--header 'Authorization: <access_token>' \
--data-raw '{
"inferenceParameterId": "<inferenceParameterId>"
}'
Response7:
{
"requestId": "3c45dc08405e",
"id": "scr_34redf451",
"state": "INIT",
"type": "QuestionnaireScore",
"measure": {
"id": "msr_67rerf231",
"name": "mental-fitness",
"variant": "v3"
}
}
STEP 8: POLL FOR EXPECTED PHQ SCORE
Wait for 5 seconds after calling API of STEP 9 and thereafter call below API at a subsequent interval of 2 seconds till state == "CONSTRUCTED".
Replace <scoreId> with the value of id attribute of Response7.
$ curl --request GET 'https://api.sondeservices.com/platform/v2/inference/scores/<scoreId>' \ --header 'Content-Type: application/json' \ --header 'Authorization: <access_token>'
Response 8:
{
"requestId": "3c45dc08405e",
"state": "CONSTRUCTED",
"id": "scr_34redf451",
"score": 27,
"type": "QuestionnaireScore",
"measure": {
"id": "msr_67rerf231",
"name": "mental-fitness",
"variant": "v3"
}
}