Overview

The following use-cases (with curl language examples) are a guide for your app development. To create and consume questionnaire for a user.

Notes:

To access create Questionnaire Api, please contact Sonde at support@sondehealth.com. Please provide your company name and address.

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 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/questionnaires.read sonde-platform/questionnaires.write sonde-platform/questionnaire-responses.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 submit a questionnaire to the Sonde Platform using Questionnaire Service, then you can share an access-token with the device having scope sonde-platform/questionnaire.write to restrict the access and prevent the misuse of privileges your client-credential is carrying.

As a developer, I want to register a questionnaire to consume it in my app.

On your backend perform the below steps create questionnaire and submit response.

STEP 1 : GET THE APPROPRIATE ACCESS-TOKEN
STEP 2: REGISTER A USER WITH SONDE HEALTH
STEP 3: CREATE QUESTIONNAIRE
STEP 4: GET QUESTIONNAIRE ON YOUR APP
STEP 5: SUBMIT QUESTIONNAIRE RESPONSE TO SERVER

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/questionnaire.write and sonde-platform/users.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 sonde-platform/questionnaire.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.

$ 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: CREATE QUESTIONNAIRE

Call the Post questionnaires API to check the questionnaire required for measure and list of languages in which questionnaire is available on API Platform.

$ curl --request POST 'https://api.sondeservices.com/platform/v1/questionnaires' \
--header 'Authorization: <access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
        "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
                    },
                    {
                        "text": "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 text temperature?",
                "isSkippable": true,
                "inputDataType": "BODY_TEMPERATURE"
            }
        ]
    }'

Response3:

{
    "id": "qnr-c79f28329",
    "language": "en",
    "requestId": "ab3e2522-d3ca-4991-a9f5-faa66371b214"
}

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

STEP 4: GET QUESTIONNAIRE ON YOUR APP

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

Below API will return questionnaire qnr_67rerf432 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:

{
    "id": "qnr-c79f28329",
    "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
                },
                {
                    "text": "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": true,
            "inputDataType": "BODY_TEMPERATURE"
        }
    ],
    "requestId": "726a8184-639c-41ed-9de7-ac7b2e79f312"
}

STEP 5: SUBMIT QUESTIONNAIRE RESPONSE TO SERVER

Ask your 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.

$ curl --request POST 'https://api.sondeservices.com/platform/v1/questionnaire-responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: <access_token>' \
--data-raw '{
    "questionnaire": {
         "id": "<qid>",
        "language": "en",
        "userIdentifier":"<subjectIdentifier>",
        "respondedAt": "1994-11-05T13:15:30Z",
        "questionResponses": [
            {
                "optionIndex": 1
            },
            
            {
                "optionIndexes": [1]
            },
            {
                "response": 4
            },
            {
                "isSkipped": true
            }
            
        ]
    }
}'

Response5:

{
    "id": "qrs_21397202f07e",
    "requestId": "a6964f06-e174-4d60-a268-2f68df8e0e07"
}

Partner Questionnaire Creation

Overview

API Credentials

API call

API response

As a developer, I want to register a questionnaire to consume it in my app.