Kintsugi Voice API

Overview

With just a few lines of code, you can use the KV API to predict sufficient presence of signals consistent with a current depressive episode using a short clips of free-form speech from a patient. Our powerful machine-learning models can predict signs of depression from voice samples acquired across a wide range of workflows and settings including, but not limited to, clinical call centers, telehealth platforms, and remote patient monitoring venues. Here, you will find all the documentation and code samples necessary to integrate KV into your clinical workflow(s).

The KV API confirms to the REST architectural style. It has predictable resource-oriented URLs, accepts a range of request bodies, returns JSON-encoded responses, and uses standard HTTP verbs and response codes.

NOTE
At present, the results of KV API are considered investigational and not a standalone diagnostic, and the results are intended for use by medical professionals as a clinical decision support tool and are not diagnostic.



Kintsugi's APIs to get a prediction consists just of 3 main APIs. Before you start a prediction, you will need to initiate a session to inform that you have the patient's consent and to get a session identifier from Kintsugi. You can do this by invoking /initiate API call. The session identifier will help you to associate the audio sample and corresponding prediction result. Once you have a session id,  you can then invoke /predict API to send the audio sample you'd like Kintsugi to analyze. While the analysis could take a few seconds, the call is non-blocking. The last API in the prediction flow is the /GET where you can get the prediction results using the session identifier.

Kintsugi offers a /feedback API which can be used to provide additional results that you may have to continuously improve our prediction models.

You will need to Initiate a Session with KV in order to proceed to the next steps of submitting an audio file with the patient’s voice sample to receive the prediction associated with that sample.

You will need to Initiate a Session with KV in order to proceed to the next steps of submitting submitting an audio file with the patient’s voice sample to receive the prediction associated with that sample.

Initiate a Session

1.0 Session

A session comprises exactly two key interactions that result in a single prediction:

1. First, you submit an audio file of the recording of the patient’s voice to KV.

2. Next, you receive a response containing a prediction.

You will need to initiate a session with KV in order to proceed to the next steps of submitting an audio file with the patient’s voice sample and receiving a prediction associated with that sample. Optionally submit patient demographic information including age, gender, race, ethnicity, the patient's 5-digit US zipcode of residence, English language proficiency, and body weight before sending an audio file for prediction. Kintsugi will associate the metadata with the audio file and prediction.

When you successfully initiate a session with KV, the KV API generates and returns to you in its response a unique session identifier that you will then use in a subsequent request to Get a Prediction from KV.

NOTE
A single session can only ever be associated with a single prediction. In other words, you will need to create a new session for every new prediction.

To initiate a session, use the Initiate endpoint as follows:

2.0 Endpoint

POST https://api.kintsugihealth.com/v2/initate

2.1 Swagger URL

https://api.kintsugihealth.com/v2/reference/flow/index.html#/initiate/post_initiate

3.0 Request

3.1 Headers

NAME

VALUE

NOTE

Accept

application/x-www-form-urlencoded

--

Content type

application/x-www-form-urlencoded

--

X-API Key

Your API Key

Account API Key to be checked.

3.2 Body

NAME

VALUE

NOTE

user_id
*required

application/json

Use this identifier to identify and track the patient. You are free to use any identifier you choose – this helps you track the patient and their associated KV predictions for your documentation.

is_initiated
*required

Boolean

+

True

+

False

Use this flag to indicate to KV whether the patient provides consent for KV to process their voice recording. Please refer to the Regulatory and Compliance section for information about collecting the patient's consent.

+

Use True to indicate that the patients has given their consent.

+

Use False to indicate that the patient has not given their consent.

Note that if the user does not provide their consent and the flag is “false" - then a session is not created, and no further processing occurs until the patient gives their consent and the user creates a new session with the flag set to "true".

metadata.age

Integer

Use this field to provide the patient's age at the time of audio collection as optional metadata for association with the patient's audio file and prediction. Integer must be >0.

metadata.gender

Enum

+

Female

+

Male

+

Other

+

Prefer Not to Specify

+

Transgender Female

+

Transgender Male

Use this field to provide the patient's gender identity as optional metadata for association with the patient's audio file and prediction.

metadata.race

Enum

+

American Indian or Alaskan Native

+

Asian

+

Black or African American

+

Native Hawaiian or Pacific Islander

+

Prefer Not to Specify

+

Two or More Races

+

White

Use this field to provide the patient's racial identity as optional metadata for association with the patient's audio file and prediction.

metadata.ethnicity

Enum

+

Hispanic, Latino, or Spanish Origin

+

Not Hispanic, Latino, or Spanish Origin

Use this field to provide the patient's age at the time of audio collection as optional metadata for association with the patient's audio file and prediction. Integer must be >0.

metadata.zipcode

String

Use this field to provide the patient's 5-digit US zipcode of current residence as optional metadata for association with the patient's audio file and prediction. String pattern: ^[0-9]{5}$.

metadata.language

Boolean

+

True

+

False

Use this field to indicate if the patient's first language is English as optional metadata for association with the patient's audio file and prediction.

metadata.weight

Integer

Use this field to provide the patient's most recent body weight in pounds (lbs) as optional metadata for association with the patient's audio file and prediction. Integer must be > 0.

4.0 Responses

NAME

VALUE

NOTE

201

{
 "session_id": "bc35e1ce-0c4e-4404-bf7e-6bae5e6c32d0"
}

KV processes the request successfully and successfully initiates a session.

401

{
 "message": "string"
}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your request will be processed accordingly.

403

{
 "message": "string"
}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

406

{
 "message": "string"
}

Consent not provided. KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your request will be processed accordingly.

422

{
 "message": "string"
}

KV is unable to use the parameters sent in the request body. More specifically, the parameters are either empty or invalid. Please use the following error responses to address the specific problem. The error is customized to the specific parameter that is either empty or valid.

For instance, if your request does not have “user_id” in the body, then you will get the following response:

{
  "error": "unsupported_metadata_spec",
  "context": {
    "user_id": "unprovided"
  }
}

If KV expects the "zipcode" to be 5 characters long and finds it to be 6 instead, then KV gives the following response:

{
  "error": "unsupported_metadata_spec",
  "context": {
    "user_id": "malformed"
  }
}

500

{
 "message": "string"
}

KV has encountered a situation and we are working to improve the flow of this request.

Predict (Submit Audio)

1.0 Predictions

KV is able to ingest a WAV audio file of the recording of the patient speaking in a single session and respond with its prediction about the presence of current symptoms of depression from their vocal features. KV supports binary predictions for the presence or absence of current significant symptoms of depression, as well as a 3-class model to stratify patients by symptom severity.



Please refer to the Audio File Specification section for detailed information about the requirements of the audio file. Different audio file types have features that can influence KV’s ability to predict signs of depression. Thus, the file must adhere to the minimum recommended standards to generate an accurate prediction. To learn how to help Kintsugi continue to ensure the accuracy of our device - please refer to the Submit Feedback section. 

Once you are ready with an audio file that meets recommended standards, use the Predict endpoint to get a prediction as follows:

NOTE
KV currently supports ingesting a pre-recorded audio file. Most commonly, as a pre-onboarding checklist item, a patient sends a voice memo describing why they are scheduling a visit along with any pre-existing conditions to note to the practitioner, typically no more than a few minutes in length. KV receives the voice memo with consent from the patient to get a prediction. While this is the most common workflow in which clients use KV today, it will soon support the ability to ingest streaming audio and predict in real-time. Stay tuned!

2.0 Endpoint

POST https://api.kintsugihealth.com/v2/prediction/

2.1 Swagger URL

https://api.kintsugihealth.com/v2/reference/flow/index.html#/predict_submit_v2

3.0 Request

3.1 Headers

NAME

VALUE

NOTE

Accept

application/json

--

Content-Type

multipart/ form-data

--

X-API Key

Your API Key

Account API Key to be checked.

3.2 Body

NAME

VALUE

NOTE

file

String

Use this field to upload binary data from the single-channel WAV 44.1 kHz audio file uploaded using a multipart/form-data POST action.

session_id

Boolean

This is the session identifier that you receive when you successfully initiate the session using the “Initiate” endpoint.

4.0 Responses

NAME

VALUE

NOTE

202

{

  "session_id": "string",

  "status": "string"

}

KV has accepted the request successfully but has not yet been acted upon.

401

{

  "message": "string"

}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

403

{

  "message": "string"

}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

404

{

  "message": "string"

}

KV is unable to find the requested resource. The session ID does not correspond to an initiated session. To get a prediction, either submit the correct session ID or initiate a new session.

406

{

  "message": "string"

}

KV is unable to complete the request because there has been an error in the audio file upload process.

409

{

  "message": "string"

}

The request conflicts with a previous request. The session ID was used with a previous precision request. Use a unique session ID for each prediction request.

422

{

  "message": "string"

}

There has been a validation error. The specification of the provided audio does not match the expected specification. Please refer to the Audio File Specification section fordetailed information about the requirements ofthe audio file.

500

{

  "message": "string"

}

KV has encountered a situation and we are working to improve the flow of this request.

Predict (Get Results)

1.0 Predictions

KV is able to ingest a WAV audio file of the recording of the patient speaking in a single session and respond with its prediction about the presence of current symptoms of depression from their vocal features. KV supports binary predictions for the presence or absence of current significant symptoms of depression, as well as a 3-class model to stratify patients by symptom severity.



Please refer to the Audio File Specification section for detailed information about the requirements of the audio file. Different audio file types have features that can influence KV’s ability to predict signs of depression. Thus, the file must adhere to the minimum recommended standards to generate an accurate prediction. To learn how to help Kintsugi continue to ensure the accuracy of our device - please refer to the Submit Feedback section. 

Once you are ready with an audio file that meets recommended standards, use the Predict endpoint to get a prediction as follows:

NOTE
KV currently supports ingesting a pre-recorded audio file. Most commonly, as a pre-onboarding checklist item, a patient sends a voice memo describing why they are scheduling a visit along with any pre-existing conditions to note to the practitioner, typically no more than a few minutes in length. KV receives the voice memo with consent from the patient to get a prediction. While this is the most common workflow in which clients use KV today, it will soon support the ability to ingest streaming audio and predict in real-time. Stay tuned!

Get the prediction associated with a given session ID. The User ID is the same as the one provided during the session initiation call.

2.0 Endpoint

GET https://api.kintsugihealth.com/v2/predict/sessions/{session_id}

2.1 Swagger URL

https://api.kintsugihealth.com/v2/reference/flow/index.html#/predict_get/get_predict_sessions__session_id_

3.0 Request

SESSION ID

3.1 Headers

NAME

VALUE

NOTE

Accept

application/json

--

Content-Type

multipart/ form-data

--

X-API Key

Your API Key

Account API Key to be checked.

3.2 Path Parameters

NAME

VALUE

NOTE

session_id

Boolean

This is the session identifier that you receive when you successfully initiate the session using the “Initiate” endpoint.

4.0 Responses

SESSION ID
NAME

VALUE

NOTE

200

{
 "actual_score": {
   "anxiety_binary": "false",
   "depression_binary": "false",
   "phq_2": [
     0
   ],
   "phq_9": [
     0
   ],
   "gad_7": [
     0
   ]
 },
 "created_at": "string",
 "is_calibrated": true,
 "model_category": "string",
 "model_granularity": "string",
 "predict_error": {
   "error": "audio_length_error",
   "message": "Audio file is less than the minimum audio length of 999.0 seconds"
 },
 "predicted_score": "string",
 "status": "string",
 "updated_at": "string"
}

KV processes the request successfully and returns a prediction.

401

{
  
  "message": "string"

}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

403

{
  
  "message": "string"

}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

404

{
  
  "message": "string"

}

KV is unable to find the requested resource. The session ID does not correspond to an initiated session. To get a prediction, either submit the correct session ID or initiate a new session.

417

{
  
 "actual_score": {
    
  "anxiety_binary": "false",
    
  "depression_binary": "false",
    
  "phq_2": [
      
    0
     
  ],
     
  "phq_9": [
      
    0
    
  ],
     
  "gad_7": [
      
    0
    
  ]
  
 },
   
 "created_at": "string",
  
 "is_calibrated": true,
  
 "model_category": "string",
  
 "model_granularity": "string",
  
 "predict_error": {
     
  "error": "audio_length_error",
    
  "message": "Audio file is less than the minimum audio length of 999.0 seconds"
  
 },
   
 "predicted_score": "string",
  
 "status": "string",
  
 "updated_at": "string"

}

Expectation failed.

422

{
  
  "message": "string"

}

The specification of the provided audio does not match the expected specification. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

500

{
  
  "message": "string"

}

KV has encountered a situation and we are working to improve the flow of this request.

The User ID is an external identifier, allowing you to track which sessions belong to a specific individual.  It can be used to pass in: 1) A Patient Identifier to associate the session with a patient on the caller's side. 2) A Provider ID to track the healthcare provider who conducted the session with the patient. 3) Any other identifier the caller may use to associate the session for future queries. The User ID is the same as the one provided during the session initiation call.

2.0 Endpoint

GET https://api.kintsugihealth.com/v2/predict/users/{user_id}

2.1 Swagger URL

https://api.kintsugihealth.com/v2/reference/flow/index.html#/predict_get/get_predict_users__user_id_

3.0 Request

USER ID

3.1 Headers

NAME

VALUE

NOTE

Accept

application/json

--

Content-Type

multipart/ form-data

--

X-API Key

Your API Key

Account API Key to be checked.

3.2 Path Parameters

NAME

VALUE

NOTE

user_id

Boolean

This is the user_id that you used when you successfully initiate the session using the “Initiate” endpoint.

4.0 Responses

USER ID
NAME

VALUE

NOTE

200

[
 {
   "actual_score": {
     "anxiety_binary": "false",
     "anxiety_sub": [
       0
     ],
     "depression_binary": "false",
     "depression_sub": [
       0
     ],
     "gad_7": [
       0
     ],
     "phq_2": [
       0
     ],
     "phq_9": [
       0
     ]
   },
   "created_at": "string",
   "is_calibrated": true,
   "model_category": "string",
   "model_granularity": "string",
   "predict_error": {
     "additional_data": {
       "additionalProp1": 0,
       "additionalProp2": 0,
       "additionalProp3": 0
     },
     "error": "audio_length_error",
     "message": "Audio file is less than the minimum audio length of 999.0 seconds"
   },
   "predicted_score": "string",
   "predicted_score_by_task": {
     "additionalProp1": "string",
     "additionalProp2": "string",
     "additionalProp3": "string"
   },
   "session_id": "string",
   "status": "string",
   "updated_at": "string"
 }
]

KV returns all the predictions and errors for all sessions associated with a given user_id.

401

{
  
  "message": "string"

}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

403

{
  
  "message": "string"

}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

422

{
  
  "message": "string"

}

The specification of the provided audio does not match the expected specification. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

500

{
  
  "message": "string"

}

KV has encountered a situation and we are working to improve the flow of this request.

Submit Feedback

1.0 Feedback

Kintsugi continues to improve our technology, which harnesses a large compliant, proprietary dataset. KV API relies solely on vocal characteristics to predict if a patient demonstrates voice signals consistent with a current depressive episode. However, additional patient-specific metadata including, but not limited to: gender, age, racial and ethnic identity, native language, education level, history of neurological or vocal conditions, and associated behavioral health inventory scores are all essential, voluntary data that help us to ensure that our KV machine learning technology continues to operate accurately for the entire diverse healthcare landscape without model drift or systemic bias. Please refer to the Regulatory and Compliance section to learn more about how we ensure the compliant collection and protection of your patients' data.

To voluntarily submit feedback to KV, use the feedback endpoint as follows:

NOTE
Under certain circumstances, users may collect both the PHQ-2 and PHQ-9 instruments separately from a patient. If a user invokes the PHQ-2 endpoint followed by the PHQ-9 endpoint, or vice-versa, the second feedback submission overrides the first. In its current design, only the most recent feedback is saved using a single session ID.

The Patient Health Questionnaire-2 (PHQ-2) inquires about the frequency of depressed mood and anhedonia over the past 2 weeks. The PHQ-2 includes the first two items of the PHQ-9. Each item has a score from 0 to 3 such that the total PHQ-2 score ranges from 0 to 6 and increases with the severity of depressed mood. Collect the PHQ-2 via self-report in patient intake forms or during a clinician encounter to screen for depression. [National HIV Curriculum].

2.0 Endpoint

PATCH https://api.kintsugihealth.com/v2/feedback/phq/2

2.1 Swagger URL

https://api.kintsugihealth.com/v2/reference/flow/index.html#/feedback/patch_feedback_phq_2

3.0 Request

PHQ-2

3.1 Headers

NAME

VALUE

NOTE

Accept

application/json

--

Content-Type

application/json

--

X-API Key

Your API Key

Account API Key to be checked.

3.2 Body

NAME

VALUE

NOTE

session_id

String

This is the session identifier that you receive when you successfully initiate the session using the “Initiate” endpoint.


actual_score

[0-3 Integer, 0-3 Integer]

Use this to submit PHQ-2 results to KV. The actual_score is an array of 2 values within the 0-3 range that corresponds to the scores of PHQ-2 question 1 and PHQ-2 question 2. Integer is always constrained on interval: 0 <= i <= 3. Collect PHQ-2 labels before, during, or after the encounter in which the user records the audio sample. User feedback must be collected within 24 hours of patient audio. Feedback labels outside of this window are not accepted.

4.0 Responses

PHQ-2
NAME

VALUE

NOTE

200

N/A

KV processes the response successfully and annotates the session.

401

{
  "message": "string
}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

403

{
 "message": "string
}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

404

{
  "message": "string
}

KV is unable to find the requested resource. The session ID does not correspond to an initiated session. To get a prediction, either submit the correct session ID or initiate a new session.

409

{
  "message": "string
}

Feedback provided without prediction initiated.

422

{
  "message": "string
}

There has been a validation error. The specification of the provided audio does not match the expected specification. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

500

{
  "message": "string
}

KV has encountered a situation and we are working to improve the flow of this request.

The Patient Health Questionnaire-9 (PHQ-9) is a multipurpose instrument for screening, diagnosing, monitoring and measuring the severity of depression. Each item has a score from 0 to 3 such that the total PHQ-9 score ranges from 0 to 27 and increases with the severity of depression. Collect the PHQ-9 via self-report at in patient intake forms or during a clinician encounter to screen for depression. [National HIV Curriculum]

2.0 Endpoint

PATCH http://api.kintsugihealth.com/v2/feedback/phq/9

2.1 Swagger URL

https://api.kintsugihealth.com/v2/reference/flow/index.html#/feedback/patch_feedback_phq_9

3.0 Request

PHQ-9

3.1 Headers

NAME

VALUE

NOTE

Accept

application/json

--

Content-Type

application/json

--

X-API Key

Your API Key

Account API Key to be checked.

3.2 Body

NAME

VALUE

NOTE

session_id

String

This is the session identifier that you receive when you successfully initiate the session using the “Initiate” endpoint.


actual_score

[0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer]

Use this to submit PHQ-9 results to KV. The actual_score is an array of 9 values within the 0-3 range that corresponds to the ordered scores of PHQ-9 items. Integer is always constrained on interval: 0 <= i <= 3. Collect PHQ-9 labels before, during, or after the encounter in which the user records the audio sample. User feedback must be collected within 24 hours of patient audio. Feedback labels outside of this window are not accepted.

4.0 Responses

PHQ-9
NAME

VALUE

NOTE

200

N/A

KV processes the response successfully and annotates the session.

401

{
  "message": "string
}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

403

{
 "message": "string
}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

404

{
  "message": "string
}

KV is unable to find the requested resource. The session ID does not correspond to an initiated session. To get a prediction, either submit the correct session ID or initiate a new session.

409

{
  "message": "string
}

Feedback provided without prediction initiated.

422

{
  "message": "string
}

There has been a validation error. The specification of the provided audio does not match the expected specification. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

500

{
  "message": "string
}

KV has encountered a situation and we are working to improve the flow of this request.

The General Anxiety Disorder-7 (GAD-7) is a multipurpose instrument for screening, diagnosing, monitoring and measuring the severity of anxiety. The total GAD-7 score ranges from 0 to 21 and increases with the severity of anxiety. Collect the GAD-7 via self-report at in patient intake forms or during a clinician encounter to screen for anxiety.  [National HIV Curriculum]

2.0 Endpoint

PATCH https://api.kintsugihealth.com/v2/feedback/gad/7

2.1 Swagger URL

https://api.kintsugihealth.com/v2/reference/flow/index.html#/feedback/patch_feedback_gad_7

3.0 Request

GAD-7

3.1 Headers

NAME

VALUE

NOTE

Accept

application/json

--

Content-Type

application/json

--

X-API Key

Your API Key

Account API Key to be checked.

3.2 Body

NAME

VALUE

NOTE

session_id

String

This is the session identifier that you receive when you successfully initiate the session using the “Initiate” endpoint.


actual_score

[0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer, 0-3 Integer]

Use this to submit GAD-7 results to KV. The actual_score is an array of 7 values within the 0-3 range that corresponds to the ordered scores of GAD-7 items. Each integer is always constrained within the interval: 0 <= i <= 3. Collect GAD-7 labels before, during, or after the encounter in which the user records the audio sample. User feedback must be collected within 24 hours of the patient audio. Feedback labels outside of this window are not accepted.

4.0 Responses

GAD-7
NAME

VALUE

NOTE

200

N/A

KV processes the response successfully and annotates the session.

401

{
  "message": "string
}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

403

{
 "message": "string
}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

404

{
  "message": "string
}

KV is unable to find the requested resource. The session ID does not correspond to an initiated session. To get a prediction, either submit the correct session ID or initiate a new session.

409

{
  "message": "string
}

Feedback provided without prediction initiated.

422

{
  "message": "string
}

There has been a validation error. The specification of the provided audio does not match the expected specification. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

500

{
  "message": "string
}

KV has encountered a situation and we are working to improve the flow of this request.

The Binary endpoint accepts the results of a clinical interview evaluation for depression. Clinical interviews are used to formally diagnose a patient with depression and are typically conducted by a trained Behavioral Health Practitioner or other Clinician during a telehealth encounter. Generally, the result of a clinical interview is true, false, or in some instances, indeterminate for a diagnosis of a current depressive episode.

2.0 Endpoint

PATCH https://api.kintsugihealth.com/v2/feedback/depression/binary

2.1 Full URL

https://api.kintsugihealth.com/v2/reference/flow/index.html#/feedback/patch_feedback_depression_binary

3.0 Request

BINARY

3.1 Headers

NAME

VALUE

NOTE

Accept

application/json

--

Content-Type

application/json

--

X-API Key

Your API Key

Account API Key to be checked.

3.3 Body

NAME

VALUE

NOTE

session_id

String

This is the session identifier that you receive when you successfully initiate the session using the “Initiate” endpoint.

actual_score

Boolean

+

True

+

False

+

Additional_consideration_required

+

Use True if the interview resulted in a positive diagnosis for depression.

+

Use False if the interview resulted in a negative diagnosis for depression.

+

Use Additional_consideration_required if the interview resulted in a negative diagnosis for depression

Use this to submit a feedback to KV comprising the actual binary depression result from a behavioral health inventory or clinician interview conducted before, during, or after the encounter in which the user records the audio sample. User feedback labels must be collected within 24 hours of patient audio. Feedback labels outside of this window are not accepted.

4.0 Responses

BINARY
NAME

VALUE

NOTE

200

N/A

KV processes the response successfully and annotates the session.

401

{
  "message": "string
}

KV fails to authorize the request. The API key is valid, and the API authenticates a session. However, you currently do not have permission to see the result of this request. As soon as Kintsugi permits you, your requests will start going through.

403

{
 "message": "string
}

KV fails to authenticate the request. The API Key is invalid, and you are not an authenticated user. Ensure you provide an API key, not an activation token or other identifier.

404

{
  "message": "string
}

KV is unable to find the requested resource. The session ID does not correspond to an initiated session. To get a prediction, either submit the correct session ID or initiate a new session.

409

{
  "message": "string
}

Feedback provided without prediction initiated.

422

{
  "message": "string
}

There has been a validation error. The specification of the provided audio does not match the expected specification. Please refer to the Audio File Specification section for detailed information about the requirements of the audio file.

500

{
  "message": "string
}

KV has encountered a situation and we are working to improve the flow of this request.

Sample code of the complete flow


import fetch from 'node-fetch'
import FormData from 'form-data'
import fs from 'fs'
import path from 'path'


const API_KEY = 'your api key'
const USER_ID = 'user_id from your system'
const VOICE_SAMPLE = path.resolve('Sub_PHQ0_GAD0_I.wav')

// Create authentication headers.
const headers = {'X-API-Key': API_KEY}

// Initiate session between the patient and a doctor.
const initiateFormData = new FormData()
initiateFormData.append('user_id', USER_ID)
initiateFormData.append('is_initiated', 'true') // Send boolean as string in form data
const initiateResp = await fetch('https://api.kintsugihealth.com/v1/initiate', {
  method: 'POST',
  headers: { ...headers, ...initiateFormData.getHeaders() },
  body: initiateFormData,
})

if (!initiateResp.ok) {
  throw new Error(`HTTP error! status: ${initiateResp.status}`)
}


// Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
let initiateData = await initiateResp.json()
const sessionID = initiateData.session_id


// *Binary: Make a prediction for the specified patient's voice sample.
const predictionFormData = new FormData()
predictionFormData.append('file', fs.createReadStream(VOICE_SAMPLE))
predictionFormData.append('session_id', sessionID)
let predictionResp = await fetch('https://api.kintsugihealth.com/v1/predict/server/depression/binary', {
  method: 'POST',
  headers: { ...headers, ...predictionFormData.getHeaders() },
  body: predictionFormData
})

if (!predictionResp.ok) {
  throw new Error(`HTTP error! status: ${predictionResp.status}`)
}


// *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
let feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/phq/2', {
  method: 'PATCH',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({'session_id': sessionID, 'actual_score': [1, 2]})
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}


// *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/phq/9', {
  method: 'PATCH',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({'session_id': sessionID, 'actual_score': [1, 2, 3, 1, 2, 3, 1, 2, 3]})
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}


// *Binary: Provide a doctor's feedback on the quality of the prediction.
const feedbackFormData = new FormData()
feedbackFormData.append('session_id', sessionID)
feedbackFormData.append('actual_score', 'true')
feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/depression/binary', {
  method: 'PATCH',
  headers: { ...headers, ...feedbackFormData.getHeaders() },
  body: feedbackFormData,
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}

console.log('The prediction was completed successfully!')
        


import fetch from 'node-fetch'
import FormData from 'form-data'
import fs from 'fs'
import path from 'path'


const API_KEY = 'your api key'
const USER_ID = 'user_id from your system'
const VOICE_SAMPLE = path.resolve('Sub_PHQ0_GAD0_I.wav')

// Create authentication headers.
const headers = {'X-API-Key': API_KEY}

// Initiate session between the patient and a doctor.
const initiateFormData = new FormData()
initiateFormData.append('user_id', USER_ID)
initiateFormData.append('is_initiated', 'true') // Send boolean as string in form data
const initiateResp = await fetch('https://api.kintsugihealth.com/v1/initiate', {
  method: 'POST',
  headers: { ...headers, ...initiateFormData.getHeaders() },
  body: initiateFormData,
})

if (!initiateResp.ok) {
  throw new Error(`HTTP error! status: ${initiateResp.status}`)
}


// Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
let initiateData = await initiateResp.json()
const sessionID = initiateData.session_id


// Severity: Make a prediction for the specified patient's voice sample.
const predictionFormData = new FormData()
predictionFormData.append('file', fs.createReadStream(VOICE_SAMPLE))
predictionFormData.append('session_id', sessionID)
let predictionResp = await fetch('https://api.kintsugihealth.com/v1/predict/server/depression/severity', {
  method: 'POST',
  headers: { ...headers, ...predictionFormData.getHeaders() },
  body: predictionFormData
})

if (!predictionResp.ok) {
  throw new Error(`HTTP error! status: ${predictionResp.status}`)
}


// *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
let feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/phq/2', {
  method: 'PATCH',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({'session_id': sessionID, 'actual_score': [1, 2]})
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}


// *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/phq/9', {
  method: 'PATCH',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({'session_id': sessionID, 'actual_score': [1, 2, 3, 1, 2, 3, 1, 2, 3]})
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}

console.log('The prediction was completed successfully!')
        


import requests

API_KEY = '<your api key>'
USER_ID = '<user_id from your system>'
VOICE_SAMPLE = "Sub_PHQ0_GAD0_I.wav"

# Create an HTTP Client. Provide authentication credentials.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})

# Initiate session between the patient and a doctor.
initiate_resp = session.post(
    url="https://api.kintsugihealth.com/v1/initiate",
    data={"user_id": USER_ID, "is_initiated": True},
)
initiate_resp.raise_for_status()

# Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
session_id = initiate_resp.json()["session_id"]

# Make a prediction for the specified patient's voice sample.
with open(VOICE_SAMPLE, 'rb') as patient_voice_sample:
    prediction_resp = session.post(
        url="https://api.kintsugihealth.com/v1/predict/server/depression/binary",
        files={'file': patient_voice_sample},
        data={"session_id": session_id},
    )
    prediction_resp.raise_for_status()

# *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/2",
    json={"session_id": session_id, "actual_score": [1, 2]},
)
feedback_resp.raise_for_status()

# *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/9",
    json={"session_id": session_id, "actual_score": [1, 2, 3, 1, 2, 3, 1, 2, 3]},
)
feedback_resp.raise_for_status()

# *Binary: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/depression/binary",
    data={"session_id": session_id, "actual_score": "true"},
)
feedback_resp.raise_for_status()

print("The prediction was completed successfully!")


import requests

API_KEY = '<your api key>'
USER_ID = '<user_id from your system>'
VOICE_SAMPLE = "Sub_PHQ0_GAD0_I.wav"

# Create an HTTP Client. Provide authentication credentials.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})

# Initiate session between the patient and a doctor.
initiate_resp = session.post(
    url="https://api.kintsugihealth.com/v1/initiate",
    data={"user_id": USER_ID, "is_initiated": True},
)
initiate_resp.raise_for_status()

# Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
session_id = initiate_resp.json()["session_id"]

# Make a prediction for the specified patient's voice sample.
with open(VOICE_SAMPLE, 'rb') as patient_voice_sample:
    prediction_resp = session.post(
        url="https://api.kintsugihealth.com/v1/predict/server/depression/severity",
        files={'file': patient_voice_sample},
        data={"session_id": session_id},
    )
    prediction_resp.raise_for_status()

# *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/2",
    json={"session_id": session_id, "actual_score": [1, 2]},
)
feedback_resp.raise_for_status()

# *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/9",
    json={"session_id": session_id, "actual_score": [1, 2, 3, 1, 2, 3, 1, 2, 3]},
)
feedback_resp.raise_for_status()

print("The prediction was completed successfully!")