Mental Fitness M3 Scores

Sonde Health API Platform Documentation

Mental Fitness M3 Scores

Overview

The following is a use case example for administrating an M3 in your application and returning a user score. The M3 score indicates the overall level of mental health symptom burden. A score greater than 32 is
flagged as High.

Notes:

  • To access Mental Fitness M3 score functionality, please contact Sonde at support@sondehealth.com. Please provide your company name and contact information.

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 the 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/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.

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 M3
STEP 4: GET QUESTIONNAIRE FOR THE M3
STEP 5: SUBMIT QUESTIONNAIRE RESPONSE TO THE SERVER
STEP 6: CREATE AN 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/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.

Note - Partners can send their userIdentifier in query parameter in below API if they wish to register a user with Sonde Heath using their user identifier, this will help Partners to map Sonde data

$ 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 M3 QUESTIONNAIRE REQUIRED TO MENTAL-FITNESS

Call the /measures/name/{measureName}?variant=v1 API to check the questionnaire required for measure and list of languages in which the questionnaire is available on the API Platform.

curl --request GET 'https://api.sondeservices.com/platform/v1/measures/name/m3?variant=v1' \ --header 'Authorization:<access_token>'

 

Response3:

{ "id": "msr_a1484a355", "name": "m3", "questionnaire": { "id": "qnr-6b8428b25", "title": "M3_V1", "languages": [ "en" ] }, "requestId": "1607c153-6689-41c6-b90b-e5d9c44bfe00" }

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

 

STEP 4: GET THE M3 QUESTIONNAIRE FOR THE M3 ASSESSMENT

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_e23er432w", "title": "M3_V1", "language": "en", "questions": [ { "type": "MULTIPLE_CHOICE", "text": "I feel sad, down in the dumps or unhappy", "isSkippable": false, "options": [ { "text": "Not at all", "score": 0 }, { "text": "Rarely", "score": 1 }, { "text": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "score": 2 }, { "text": "Often", "score": 3 }, { "text": "Most of the time", "score": 4 } ] }, { "type": "MULTIPLE_CHOICE", "text": "I have difficulty sleeping", "isSkippable": false, "options": [ { "text": "Not at all", "score": 0 }, { "text": "Rarely", "score": 1 }, { "text": "Sometimes", "score": 2 }, { "text": "Often", "score": 3 }, { "text": "Most of the time", "score": 4 } ] }, { "type": "MULTIPLE_CHOICE", "text": "I sleep too much", "isSkippable": false, "options": [ { "text": "Not at all", "score": 0 }, { "text": "Rarely", "score": 1 }, { "text": "Sometimes", "score": 2 }, { "text": "Often", "score": 3 }, { "text": "Most of the time", "score": 4 } ] }, { "type": "MULTIPLE_CHOICE", "text": "I have lost some appetite", "isSkippable": false, "options": [ { "text": "Not at all", "score": 0 }, { "text": "Rarely", "score": 1 }, { "text": "Sometimes", "score": 2 }, { "text": "Often", "score": 3 }, { "text": "Most of the time", "score": 4 } ] }, { "type": "MULTIPLE_CHOICE", "text": "I am eating more", "isSkippable": false, "options": [ { "text": "Not at all", "score": 0 }, { "text": "Rarely", "score": 1 }, { "text": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "score": 2 }, { "text": "Often", "score": 3 }, { "text": "Most of the time", "score": 4 } ] }, { "type": "MULTIPLE_CHOICE", "text": "I have more energy than usual", "isSkippable": false, "options": [ { "text": "Not at all", "score": 0 }, { "text": "Rarely", "score": 1 }, { "text": "Sometimes", "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": "Sometimes", "score": 2 }, { "text": "Often", "score": 3 }, { "text": "Most of the time", "score": 4 } ] }, { "type": "MULTIPLE_CHOICE", "text": "I have felt unusually excited, revved up or high", "isSkippable": false, "options": [ { "text": "Not at all", "score": 0 }, { "text": "Rarely", "score": 1 }, { "text": "Sometimes", "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": "Sometimes", "score": 2 }, { "text": "Often", "score": 3 }, { "text": "Most of the time", "score": 4 } ] }, { "type": "MULTIPLE_CHOICE", "text": "interferes with work or school", "isSkippable": false, "options": [ { "text": "Not at all", "score": 0 }, { "text": "Rarely", "score": 1 }, { "text": "Sometimes", "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": "Sometimes", "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": "Sometimes", "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": "Sometimes", "score": 2 }, { "text": "Often", "score": 3 }, { "text": "Most of the time", "score": 4 } ] } ], "requestId": "c8c176f9-1225-4929-a03a-c4c561babdaf" }

 

STEP 5: SUBMIT 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 M3.

$ 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": 2 }, { "optionIndex": 1 }, { "optionIndex": 0 }, { "optionIndex": 3 }, { "optionIndex": 4 }, { "optionIndex": 2 }, { "optionIndex": 3 }, { "optionIndex": 1 }, { "optionIndex": 1 }, { "optionIndex": 3 }, { "optionIndex": 4 } ] } }'

 Response5:

Copy id attribute’s value. It is required in STEP 6.

{ "id": "qrs_09d24ef60e73" "requestId": "23454556", }

 

STEP 6: CREATE AN 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": "M3QuestionnaireScore", "parameter": { "measure": { "name": "m3", "variant": "v1" }, "questionnaireResponse": { "id": "<questionnaireResponseId>" } } }'

Response6:

{ "requestId": "f63d575a-f4d1-4343-9544-b96b1ac16b38", "questionnaireResponse": "qrs_644596b20363", "id": "inp_8e01f3adf", "type": "M3QuestionnaireScoreInferenceParameter" }

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": "MultiScore", "measure": { "id": "msr_67rerf231", "name": "m3", "variant": "v1" } }

 

STEP 8: POLL FOR EXPECTED M3 SCORE

Wait for 5 seconds after calling the API of STEP 7 and thereafter call the below API at a subsequent interval of 2 seconds till state == "CONSTRUCTED".

Replace <scoreId> with the value of the 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": 18, "type": "MultiScore", "functionalImpairment" : 0, "suicidalIdeation": 0, "subScore": [ { "id": "scr_34redf2232", "disorderName": "Depression", "score": { "value": 5 } }, { "id": "scr_34redf2233", "disorderName": "Bipolar", "score": { "value": 4 } }, { "id": "scr_34redf2234", "disorderName": "Anxiety", "score": { "value": 3 } }, { "id": "scr_34redf2235", "disorderName": "PTSD", "score": { "value": 6 } } ], "measure": { "id": "msr_67rerf231", "name": "m3", "variant": "v1" } }

The user’s Mental Fitness M3 score is 31.

For the score and associated severity level, please check Mental Fitness M3 Score.

 

Sonde Health