Overview

Use these use-cases (with curl language examples) as a guide for your app development.

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

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

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 score for Health Check “XYZ”.

Score an “XYZ” health condition with the Sonde Platform “XYZ” 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 AUDIO FILE
STEP 4: UPLOAD YOUR AUDIO FILE
STEP 5: LOOK FOR QUESTIONNAIRE REQUIRED FOR MEASURE
STEP 6: GET QUESTIONNAIRE FOR THE MEASURE
STEP 7: SUBMIT QUESTIONNAIRE RESPONSE TO SERVER
STEP 8: ASK FOR THE 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 /wiki/spaces/SHPDV1/pages/1405517833 sonde-platform/scores.write , sonde-platform/users.write, sonde-platform/questionnaires.read, sonde-platform/questionnaire-responses.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/storage.write sonde-platform/questionnaires.read sonde-platform/questionnaire-responses.write'

Response 1:

{
  "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 user sign-up process.

$ 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"
    }
}'

Response 2:

Capture the userIdentifier, in the below response wiNODNXcm. This userIdentifier will be required while calling the /inference/score API in following steps.

{
  "requestId": "23454556"
  "userIdentifier": "wiNODNXcm"
}

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 Response 1 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 Vocal Biomarkers - Health Checks .

countryCode should be the country information which you have used while creating the account with Sonde Health (account creation is manual at this time).

$ curl --request POST 'https://api.sondeservices.com/platform/v1/storage/files' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "fileType": "wav",
  "countryCode": "US",
  "userIdentifier": "<userIdentifier>"
}'

Response 3:

The response is shown for illustration purposes.

{
  "requestId": "2345234"
  "signedURL": "https://s3.aws.sondesamle.bucket/234234232ce4f21d-751a-4eb3-a5c3-9061bb2e90b342323",
  "filePath": "https://s3.aws.sondesamle.bucket/2342342342323"
}

The signedURL is required in STEP 4.

The filePath is required in STEP 8.

STEP 4: UPLOAD YOUR AUDIO FILE

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 Response 3.

curl --request PUT '<signedURL>' \
--header 'Content-Type: audio/wave' \
--data-binary '@<audioFilePath>'

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

STEP 5: LOOK FOR QUESTIONNAIRE REQUIRED FOR MEASURE

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

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

Response 5:

{
  "id": "3c45dc0840er",
  "name": "XYZ",
  "questionnaire": {
    "id": "qnr_e23er432w",
    "title": "COVID-19",
    "languages": [
       "en"
    ]
  }
}

questionnaire.id and questionnaire.languages is required in STEP 6.

STEP 6: GET QUESTIONNAIRE FOR THE MEASURE

Call /questionnaires/{questionnaireId}?language=<language> to get questionnaire.

Below API will return questionnaire qnr_e23er432w in English language.

Replace <access_token> with the value of the access_token attribute of Response 1

curl --request GET 'https://api.sondeservices.com/platform/v1/questionnaires/qnr_e23er432w?language=en' \
--header 'Authorization:<access_token>'

Response 6:

{
  "id": "qnr_e23er432w",
  "title": "covid_19",
  "language": "en",
  "questions": [
    {
      "type": "MULTIPLE_CHOICE",
      "text": "Have you been within 6 feet of a person with a lab confirmed case of COVID-19 or with symptoms of COVID-19 for at least 15 minutes, or had direct contact with their mucus or saliva,in the past 14 days?",
      "isSkippable": false,
      "options": [
        {
          "text": "No",
          "score": 0
        },
        {
          "text": "Yes",
          "score": 1
        }
      ]
    },
    {
      "type": "MULTIPLE_SELECT",
      "text": "In the last 48 hours, have you had any of the following NEW symptoms? Select all that apply.",
      "isSkippable": false,
      "options": [
        {
          "text": "Fever of 100.4° F or above",
          "score": 3
        },
        {
          "body": "Cough",
          "score": 2
        },
        {
          "text": "Trouble breathing",
          "score": 1
        },
        {
          "text": "None of the above",
          "score": 0
        }
      ]
    },
    {
      "type": "TEXT_FIELD",
      "text": "How many covid center do you have in your city?",
      "isSkippable": true,
      "inputDataType": "INTEGER"
    },
    {
      "type": "TEXT_FIELD",
      "text": "What is your body temperature?",
      "isSkippable": false,
      "inputDataType": "STRING"
    }
  ]
}

STEP 7: SUBMIT QUESTIONNAIRE RESPONSE TO SERVER

Ask questionnaire (Got in STEP 6) to your app user and use API POST /questionnaire-responses to submit response to server

Replace <access_token> with the value of the access_token attribute of Response 1
Replace <questionnaireId> with the value of the id attribute of Response6
Replace <language> with the value of one of the language received in languages attribute of Response6
Replace <userIdentifier> with the value of userIdentifier attribute of Response2
Fill-up questionnaire.questionResponses as per user response to questionnaire

$ 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
      },
      {
        "optionIndexes": [
          0,
          2
        ]
      },
      {
        "isSkipped": true
      },
      {
        "response": "104F"
      }
    ]
  }
}'

Response 7:

{
  "id": "qrs_67ytu89iu"
}

id is required in STEP 8

STEP 8: ASK FOR EXPECTED MEASURE SCORE

Call the /inference/score API to get the "XYZ" score. Refer to the below curl command.

Replace <access_token> with the value of the access_token attribute of Response 1
Replace <userIdentifier> with the value of userIdentifier attribute of Response 2
Replace <filePath> with the value of the path attribute of Response3
Replace <questionnaireResponseId> with the value of the id attribute of Response7

$ curl --request POST 'https://api.sondeservices.com/platform/v1/inference/scores' \
--header 'Content-Type: application/json' \
--header 'Authorization: <access_token>' \
--data-raw '{
  "userIdentifier": "<userIdentifier>",
  "filePath": "<filePath>",
  "questionnaireResponseId": "<questionnaireResponseId>",
  "measureName": "XYZ",
}'

Response 8:

{
  "requestId": "3c45dc08405e",
  "measureId": "123",
  "name": "XYZ",
  "scoreId": "baafa021c9d0",
  "score": 40
}

The User’s "XYZ" score is 40 (for score and associated severity level please check Vocal Biomarkers - Health Checks ).

Health Check with questionnaire support

Overview

API Credentials

API call

API response

As a developer, I want to generate a score for Health Check “XYZ”.