Sonde Health API Platform Documentation
Mental Fitness Voice Features API
Overview
Use these use-cases (with curl language examples) as a guide for your app development.
Notes:
Detail information on Mental Fitness is available at https://sondehealth.atlassian.net/wiki/spaces/SA/pages/2706309124
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 a 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 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/voice-feature-scores.write sonde-platform/voice-feature-scores.read sonde-platform/storage.write'Get <Base64EncodedString> using the below command
$ echo -n "<clientid>:<clientsecret>" | openssl base64 -AAPI 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.
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.
Please refer API REST API Reference for more detail on API request and response.
As a developer, I want to measure voice characteristics of user’s mental-fitness health condition
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: GET THE S3 SIGNED URL TO UPLOAD YOUR AUDIO FILE
STEP 4: UPLOAD YOUR AUDIO FILE
STEP 5: CREATE AN INFERENCE JOB FOR VOICE FEATURE AND AGGREGATE SCORE
STEP 6: POLL FOR VOICE ACOUSTIC FEATURES AND AGGREGATE 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/users.write sonde-platform/voice-feature-scores.write sonde-platform/voice-feature-scores.read 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 user sign-up process.
Replace <access_token> with the value of access_token attribute from 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. This userIdentifier will be required while calling the /inference/voice-feature-scores API in following steps.
Keep userIdentifier in your UserManagement module (or database) to later use it for same patient.userIdentifier will be used in STEP 3.
STEP 3: GET THE S3 SIGNED URL TO UPLOAD YOUR AUDIO FILE
Call Storage Service to get the signed URL. In the Authorization header put the value of the access_token attribute from Response1 and the country-code in which you want to upload the wave file.
For supported country codes and audio meta info Please check the REST API Reference).
For better measure accuracy it is recommended to upload the audio file which has the elicitation mentioned on page Mental Fitness Voice Features.
countryCode should be the country of your end-user. As per HIPAA audio file is considered as PII and hence the audio file should not leave the country of end-user.
Supported countryCode can be found at PII & PHI storage region for test data and live data
You need to make sure to provide correct countryCode of your end-user and we will make sure to provide signed-url of that country only to upload the your end-user audio file.
Replace <access_token> with the access_token attribute’s value from Response1.
Replace <userIdentifier> with the userIdentifier attribute’s value from Response2.
For detail information on capturing Mode, Please refer Capturing Mode
Response3:
The response is shown for illustration purposes.
The signedURL is required in STEP 4.
The filePath is required in STEP 5.
STEP 4: UPLOAD YOUR AUDIO FILE
Sonde recommends the following listed code snippet to record audio file:
web: Sonde vocal biomarkers do not support audio acquired from web-based devices such as computers. Please contact Sonde for additional information.
Please find the sample audio file. Download it on your machine to try out the upload API.
Replace <signedURL> with the value of signedURL attribute from Response3.
Replace <audioFilePath> with the file path of your local audio file.
Response4:
You can expect the 20X response code for the above mentioned API.
STEP 5: CREATE AN INFERENCE JOB FOR VOICE FEATURE AND AGGREGATE SCORE
Call the /inference/voice-feature-scores API to create a job for the Mental Fitness voice-feature scores. Refer to the below curl command.
Here in request:
infer.type:”Acoustic” says you want to infer acoustic voice-feature from audio-file (i.e.filePath) for given user (i.e userIdentifier)
infer.version:”<version>” says you want acoustic voice-feature of version v1. Refer link Mental Fitness Voice Features for more detail on measures and their voice-feature version available
Replace <access_token> with the value of access_token attribute from Response1.
Replace <userIdentifier> with the value of userIdentifier attribute of Response2.
Replace <filePath> with the value of the path attribute of Response3.
Response5:
STEP 6: POLL FOR VOICE ACOUSTIC FEATURES AND AGGREGATE SCORE
Wait for 15 seconds after calling API of STEP 5 and thereafter call below API at subsequent interval of 3 seconds till status == "DONE".
Replace <access_token> with the value of access_token attribute from Response1.
Replace <jobId> with the value of jobId attribute from Response5.
Response6:
Aggregated Score is available at result.inference[].score.value
Individual voice feature scores are available at result.inference[].voiceFeatures[].score
Refer link Mental Fitness Voice Features for possible voice-features and their score ranges
On status == "DONE", you will get voice-feature and aggregated score for mental-fitness health condition.
Please refer API REST API Reference for more detail on API request, response.
Sonde Health