Overview

The following is a use case example for administrating a PHQ-2 and returning a user score. The PHQ-2 is a questionnaire about the frequency of depressed mood and anhedonia over the past two weeks. The PHQ-2 questionnaire is just one example. The APIs support any set of questions and score calculation.

Notes:

• To access Mental Fitness PHQ2 Score, please contact Sonde at support@sondehealth.com. Please provide your company name and contact.

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

Get <Base64EncodedString> using the below command

API response

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 a PHQ-2 score for mental fitness.

Score Mental Fitness health condition with the Sonde Platform “Patient Health Questionnaire-2”.

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 QUESTIONNAIRE REQUIRED FOR MENTAL-FITNESS
STEP 4: GET QUESTIONNAIRE FOR THE MENTAL-FITNESS
STEP 5: SUBMIT QUESTIONNAIRE RESPONSE TO SERVER
STEP 6: CREATE INFERENCE PARAMETER FOR PHQ SCORE
STEP 7: ASK FOR THE EXPECTED PHQ-2 SCORE.

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.

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.

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

• For Api details Please check the REST API Reference .

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: 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.

Response3:

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

STEP 4: GET THE PHQ-2 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.

Response4:

Note: Your app should not have string matching logic on questions[].text. Sonde can edit this text.

STEP 5: SUBMIT QUESTIONNAIRE RESPONSE TO SERVER

Ask PHQ2 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:

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

STEP 6: CREATE INFERENCE PARAMETER FOR PHQ 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 PHQ-2 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.

Response6:

id is required in STEP 7.

STEP 7: ASK FOR THE EXPECTED PHQ2 SCORE

Call the /v2/inference/scores API to trigger PHQ-2 score processing. Refer to the below curl command.

Replace <inferenceParameterId> with the value of id attribute of Response6.

Response7:

STEP 8: POLL FOR EXPECTED PHQ-2 SCORE

Wait for 5 seconds after calling API of STEP 7 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.

Response 8:

The User’s Mental Fitness PHQ-2 score is 3.

For score and associated severity level please check Mental Fitness PHQ-2 Score.

For generating a Mental Fitness Questionnaire Score on a questionnaire other than PHQ2 then refer Partner Questionnaire Integration with APIs.