Sonde Health API Platform Documentation

Respiratory Symptoms Risk (variant: V2)

Owned by Mohdsiddique Bagwan (Unlicensed)
Last updated: Sept 26, 2023 by Aman Jain
8 min read

Overview

The following use-cases (with curl language examples) are a guide for your app development. To return a score for a user, this version requires two back-to-back voice samples that have passed the elicitation checks.

Notes:

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 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/storage.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 a Respiratory Symptoms Risk score.

Score Respiratory Symptoms Risk health condition with the Sonde Platform “Respiratory Symptoms Risk” measure.

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 FIRST AUDIO FILE
STEP 4: UPLOAD YOUR FIRST AUDIO FILE
STEP 5: CREATE INFERENCE PARAMETER FOR FIRST AUDIO FILE
STEP 6: GET THE S3 SIGNED URL TO UPLOAD YOUR SECOND AUDIO FILE
STEP 7: UPLOAD YOUR SECOND AUDIO FILE
STEP 8: UPDATE INFERENCE PARAMETER FOR SECOND AUDIO FILE
STEP 9: ASK FOR THE EXPECTED MEASURE SCORE
STEP 10: POLL FOR EXPECTED MEASURE 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

 

 

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: GET THE S3 SIGNED URL TO UPLOAD YOUR FIRST 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 better measure accuracy it is recommended to upload the audio file which has the elicitation mentioned on page Respiratory Symptoms Risk.

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 https://sondehealth.atlassian.net/wiki/spaces/SA/pages/2693333000/Account#PII-&-PHI-storage-region-for-test-data-and-live-data

 

Replace <userIdentifier> with the value of the userIdentifier attribute of 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 FIRST AUDIO FILE

Sonde recommends the following listed code snippet to record the audio file:

Please find the sample audio file. Download it on your machine to try out the upload API

 

Upload a local audio file to <signedURL>.

In the below curl command replace <audioFilePath> with your local file path and <signedURL> with the value of the signedURL attribute received in Response3.

 

Response4:

You can expect the 20X response code for the above-mentioned API.

 

STEP 5: CREATE INFERENCE PARAMETER FOR FIRST AUDIO FILE

Call /platform/v2/inference/inference-parameters to create InferenceParameter resource.

This API will return a measure-parameters resource’s id if validation applicable for given measure is passed.

This API performs below validation on the input path

Note: Your app should gracefully handle any extra validation which may be added in future releases of the Sonde API Platform.

Replace <filePath> with the value of filePath attribute of Response3.

 

Response5:

The HTTP status code will be 202 to indicates additional input is still required in the PUT API call of inference-parameter resource.

In case respiratory-symptoms-risk:v2 the additional input is a second audio file.

The response is shown for illustration purposes.

id is required in STEP 8 & STEP 9.

 

 

STEP 6: GET THE S3 SIGNED URL TO UPLOAD YOUR SECOND 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 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 Respiratory Symptoms Risk

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 https://sondehealth.atlassian.net/wiki/spaces/SA/pages/2693333000/Account#PII-&-PHI-storage-region-for-test-data-and-live-data

Replace <userIdentifier> with the value of the userIdentifier attribute of Response2.

 

Response6:

The response is shown for illustration purposes.

The signedURL is required in STEP 7.

The filePath is required in STEP 8.

 

STEP 7: UPLOAD YOUR SECOND AUDIO FILE

Sonde recommends the following listed code snippet to record audio file:

 

Please find the sample audio file. Download it on your machine to try out the upload API

 

Upload a local audio file to <signedURL>.

In the below curl command replace <audioFilePath> with your local file path and <signedURL> with the value of the signedURL attribute received in Response6.

 

Response7:

You can expect the 20X response code for the above-mentioned API.

 

STEP 8: UPDATE INFERENCE PARAMETER FOR SECOND AUDIO FILE

Add a second audio file into measure-parameters

This API performs below validation on filePath

  • Provided filePath should be present on Server

  • Perform elicitation check configured for the given measure. For example Ahh elicitation

  • The user of this audio file should match with the user of the first audio file

  • Previously added audio file and this audio file should be different

  • Audio file duration should be as per Respiratory Symptoms Risk

  • Country of a previously added audio file and this audio file should be same

  • The audio file should be as per Audio Format Specifications

Note: Your app should gracefully handle any extra validation which may be added in future releases of Sonde API Platform.

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

Response8:

 

STEP 9: ASK FOR THE EXPECTED MEASURE SCORE

Call the /v2/inference/scores API to trigger Respiratory Symptoms Risk score processing. Refer to the below curl command.

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

Response9:

 

STEP 10: POLL FOR EXPECTED MEASURE 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 Response9.

 

Response10:

The User’s Respiratory Symptoms Risk score is 40.

For score and associated severity level please check Respiratory Symptoms Risk.

 

Sonde Health