How to call the /api/assessments/add endpoint

This article explains how to use the /api/assessments/add endpoint to submit assessment responses into Sunwave. This endpoint is commonly used to push assessments completed outside of Sunwave (such as external forms or integrations) into a patient or opportunity record.

Prerequisites

• Access to Chrome DevTools

• API authentication configured

• Access to the patient or opportunity chart

• A regular (non-multicolumn) assessment

  • multi-column assessments are commonly used for CIWA/COWS assessments not regular PHQ-9/GAD-7/C-SSRS assessments

Creating/Identifying the Assessment

To post to the /api/assessments/add endpoint you must address a regular (non-multicolumn) assessment:

Open

The assessment must be created using this form element

It should look like this in the forms builder:

Open

This is what that assessment looks like in a patient chart:

Open

You must collect several values before sending the request, as required by the assessment endpoint documentation. In most cases, the only way to find them is through Chrome DevTools while opening the assessment in the patient/opportunity chart. Forms Builder can help confirm the form_id, but you will still need DevTools to retrieve the assessment_uuid.

Example payload

Payload field reference

Open

• entity
  The record type the assessment should be attached to. Supported values in the schema are admission, opportunity, account, and referral. Use the ID field that matches the entity you choose.

  • admission_id
    The admission record ID. Because a patient can have multiple admissions, both the admission_id and patient_id are required to post an assessment for a patient.

  • patient_id
    The patient record ID. In Chrome DevTools, this value appears as mri, and that value maps to patient_id for this endpoint. It is not the same as the MRI displayed in the Sunwave UI.

    Open

    

  • opportunity_id
    Use this when entity is opportunity. This ID is visible in the UI:

    Open

    

  • account_id
    Use this when entity is account. This must be the Sunwave account ID, not a legacy account ID. Based on testing, the destination of account-based assessment posts may need additional verification. This is also visible via the UI:

    Open

    
    Open

    

    Please note that, unlike other parts of our API, the Legacy Account ID will not work here and the Sunwave Account ID must be used.

  • referral_id
    Use this when entity is referral.

• form_id
  The ID of the form that contains the assessment. This can be found in Chrome DevTools and may also be visible in the Forms Builder. Since DevTools is required to retrieve the assessment_uuid, it is typically easiest to obtain the form_id there as well.

  Open

  

• date
  The assessment date, formatted as YYYY-MM-DD. This acts as the Date of Service for the assessment and is used when creating the form instance.

• assessment_uuid
  The unique ID of the assessment component on the form. This is only visible in the DevTools network response or Preview tab. It does not change when you update the form element, but will be regenerated if you remove and re-add the form element.

• answers
  An array of answers to submit. Each answer must include:

  • question_id: the ID of the question being answered (zero based index or starts counting as zero)

  • answer: the exact answer text as it appears on the assessment

Important notes about answers

• Answer values must match the available answer choices exactly, character for character.

• When a question should be left unanswered, omitting it from the answers array is best practice. Sending an empty answer value can also work in some cases.

  { "answer": "", "question_id": "2" },

• After a successful submission, the response may include:

  • inserted_answers

  • invalid_answers

  • question_possible_answers
    These can help troubleshoot bad answer values.

Getting the UUID

Start with the assessment open in the patient or opportunity chart.

1. Open Chrome DevTools and select the Network tab.

2. Clear the existing network log.

3. Click the date for the form instance to trigger a new network request.

4. Open the relevant PatientChart/?mri=... request.

5. Open the Payload tab and copy:

   • form_id

   • mri, which maps to patient_id for this endpoint

   • admission_id

   • opportunity_id, if you are working in an opportunity

6. Open the Preview tab and locate:

   • the assessment_uuid

   • the question_id values

   • the valid answer choices

The Sections object is ordered to match the elements on the form, which can help you identify the correct assessment when the form contains multiple elements or assessments.

Open

Limitations

• Only one assessment can be submitted per form instance per request.

• Multiple assessments within the same form cannot be submitted in a single call.