Multi-SOAP

When using SOAP templates, you can split a single consultation into multiple separate SOAP notes or merge previously split consultations back together. This is useful when multiple patient concerns are discussed in one visit and need to be documented separately.

Prerequisites

Before using multi-SOAP functionality:

• You must have completed a consultation using a SOAP template (e.g., soap_new_complaint_api)
• You need the consultation ID from the startRecording method

Splitting a consultation

To split a consultation into multiple SOAP notes, use the splitSoap method on the Consultation object returned by startRecording:

await consultation.splitSoap();

Regeneration keeps the report length already stored on the consultation (from startRecording, including when you omitted writingStyle), with the user’s account default as fallback. The SDK does not send a new writingStyle for split or merge.

This asynchronous operation will process the consultation and create separate SOAP notes for distinct patient concerns or topics discussed during the visit.

Merging split consultations

If you’ve previously split a consultation and want to merge the SOAP notes back into a single consultation, use the mergeSoap method on the Consultation object:

await consultation.mergeSoap();

This will combine the previously split SOAP notes back into a unified consultation summary.

Example

// Start recording
const consultation = await squire.startRecording({
  inputLanguage: 'nl',
  templateId: 'soap_new_complaint_api',
});
 
// Split the consultation into multiple episodes
const splitSummary = await consultation.splitSoap();
console.log('Split result:', splitSummary);
// splitSummary contains the final summary with multiple episodes in `data`
 
// Or merge episodes back into a single consultation
const mergedSummary = await consultation.mergeSoap();
console.log('Merge result:', mergedSummary);
// mergedSummary contains the final summary with a single consolidated episode

Purged consultations

Both methods regenerate the report from the consultation’s transcript. Organizations can set a data retention policy that permanently removes that transcript on a schedule, and once it is gone the report can no longer be regenerated. splitSoap() and mergeSoap() then reject with a Squire.ApiError carrying status: 410 and code === Squire.DATA_PURGED.

import Squire from '@squirehealth/sdk';
 
try {
  await consultation.splitSoap();
} catch (error) {
  if (error instanceof Squire.ApiError && error.code === Squire.DATA_PURGED) {
    // `error.detail` names which data went and is safe to show, but it can be null
    return;
  }
  throw error;
}

Branch on error.code rather than on the message or the response shape, and treat the failure as final: the transcript is not coming back, so retrying will fail the same way. See Purged data.

Recovering a lost consultation reference

If you no longer hold a reference to the Consultation object (e.g. after a page refresh or navigation), you can reconstruct it using squire.consultation():

const consultation = squire.consultation('consultation-uuid');
 
// You can now call splitSoap / mergeSoap / getSummary as usual
const summary = await consultation.splitSoap();

This creates a Consultation instance bound to the given ID, allowing you to call any consultation method without needing the original object from startRecording.

Output format

After splitting a consultation, the returned summary will contain multiple episodes in the data array:

{
  "id": "8lbv3SJ7ObqOWh11",
  "data": [
    {
      "episode": "Episode 1",
      "template": "soap_new_complaint_api",
      "sections": [...]
    },
    {
      "episode": "Episode 2", 
      "template": "soap_new_complaint_api",
      "sections": [...]
    }
  ]
}

Each episode contains its own SOAP sections with separate patient concerns. For the complete output structure and available fields, see the output documentation.