Data output

The Squire SDK returns structured consultation data in JSON format. The data is structured according to the template used for the consultation.

View an example of a SOAP note in Dutch


{
  "id": "yoEh163Y1cHih2S1",
  "input_language": "nl",
  "output_language": "nl",
  "start_datetime": "2025-01-01T12:00:00Z",
  "end_datetime": "2025-01-01T12:30:00Z",
  "report_status": "final",
  "generation_result": "success",
  "content_format": "plain",
  "data": [
    {
      "episode": "Consultation",
      "template": "soap_new_complaint_api",
      "sections": [
        {
          "section_id": "subjective",
          "fields": {
            "summary": {}
          }
        },
        {
          "section_id": "objective",
          "fields": {
            "summary": {},
            "vital_signs": []
          }
        },
        {
          "section_id": "assessment",
          "fields": {
            "medical_coding": []
          }
        },
        {
          "section_id": "plan",
          "fields": {
            "summary": {},
            "prescribed_medication": [],
            "sick_note": {}
          }
        }
      ]
    }
  ]
}

View an example of a specialist note with free text in Dutch


{
  "id": "qIe6WDaV1dN5f6y2",
  "input_language": "nl",
  "output_language": "nl",
  "start_datetime": "2025-10-02T08:59:13.128Z",
  "end_datetime": "2025-10-02T09:00:20.405Z",
  "report_status": "final",
  "generation_result": "success",
  "content_format": "plain",
  "data": [
    {
      "episode": "Consultation",
      "template": "specialist_general_free_text_api",
      "sections": [
        {
          "section_id": "free_text",
          "fields": {
            "summary": {
              "text": "Reden van het bezoek:\n---------------------\nDiarree sinds drie dagen.\n\nAnamnese:\n---------\nSinds drie dagen frequente, waterige en losse ontlasting. Gemiddeld zes tot zeven keer per dag naar het toilet. Klachten van pijn in de onderbuik. Diarree heeft invloed op dagelijkse activiteiten.\n\nKlinisch onderzoek:\n-------------------\n-\n\nDiagnose:\n---------\nAcute diarree, waarschijnlijk infectieus van aard.\n\nBehandelingsplan:\n-----------------\n-\n\nConclusie:\n----------\nAcute diarree met frequente, waterige ontlasting en onderbuikspijn sinds drie dagen."
            }
          }
        }
      ]
    }
  ]
}

View an example of a dictation


{
  "id": "j3hc7l6TgeKL15GQ",
  "input_language": "nl",
  "output_language": "en",
  "start_datetime": "2025-10-10T14:33:49.646709+00:00",
  "end_datetime": null,
  "report_status": "intermediate",
  "generation_result": "success",
  "content_format": "plain",
  "data": [
    {
      "episode": "Dictation",
      "template": "dictation_api",
      "sections": [
        {
          "section_id": "transcription",
          "fields": {
            "fixed": {
              "text": "Patient complains of a sore throat."
            },
            "ongoing": {
              "text": "And a headache for the last two"
            }
          }
        }
      ]
    }
  ]
}

View an example of a split SOAP note with multiple episodes


{
  "id": "8lbv3SJ7ObqOWh11",
  "input_language": "nl",
  "output_language": "nl",
  "start_datetime": "2026-01-30T09:58:01.276040+00:00",
  "end_datetime": "2026-01-30T09:58:29.360123+00:00",
  "report_status": "final",
  "generation_result": "success",
  "generation_result_message": null,
  "content_format": "plain",
  "data": [
    {
      "episode": "Episode 1",
      "template": "soap_new_complaint_api",
      "sections": [
        {
          "section_id": "subjective",
          "fields": {
            "summary": {
              "text": "Koorts, 39°C. Ziektebriefje gevraagd."
            }
          }
        },
        {
          "section_id": "objective",
          "fields": {
            "summary": {
              "text": "Lichaamstemperatuur 39°C."
            },
            "vital_signs": [
              {
                "vital_sign_id": "body_temperature",
                "unit": "°C",
                "value": 39
              }
            ]
          }
        },
        {
          "section_id": "assessment",
          "fields": {
            "medical_coding": [
              {
                "icd_10": "R50",
                "icpc_2": "A03",
                "ibui": "10049426",
                "description": "koorts van onbekende oorsprong"
              }
            ]
          }
        },
        {
          "section_id": "plan",
          "fields": {
            "summary": {
              "text": "Ibuprofen en paracetamol voorgeschreven. Ziektebriefje tot einde week."
            },
            "prescribed_medication": [
              {
                "active_ingredient": "Ibuprofen",
                "brand_name": null,
                "pharmaceutical_form": null,
                "pack_size": null,
                "atc_code": "M01AE01"
              },
              {
                "active_ingredient": "Paracetamol",
                "brand_name": null,
                "pharmaceutical_form": null,
                "pack_size": null,
                "atc_code": "N02BE01"
              }
            ],
            "sick_note": {
              "from_date": "2026-01-30",
              "to_date": "2026-02-02"
            }
          }
        }
      ]
    },
    {
      "episode": "Episode 2",
      "template": "soap_new_complaint_api",
      "sections": [
        {
          "section_id": "subjective",
          "fields": {
            "summary": {
              "text": "Kniepijn, vooral bij lopen."
            }
          }
        },
        {
          "section_id": "objective",
          "fields": {
            "summary": {
              "text": ""
            },
            "vital_signs": []
          }
        },
        {
          "section_id": "assessment",
          "fields": {
            "medical_coding": [
              {
                "icd_10": "M25.5",
                "icpc_2": "L20",
                "ibui": "10037707",
                "description": "gewrichtsklachten"
              }
            ]
          }
        },
        {
          "section_id": "plan",
          "fields": {
            "summary": {
              "text": "2 weken rust, niet lopen. Daarna geleidelijk hervatten."
            },
            "prescribed_medication": [],
            "sick_note": null
          }
        }
      ]
    }
  ]
}

Metadata fields

Each API response includes metadata fields that describe the consultation and the generated report. These fields are returned at the top level of the response object.

Field	Type	Description
`id`	`string`	Unique identifier for the consultation.
`input_language`	`string`	Language code of the input audio.
`output_language`	`string`	Language code of the generated report.
`start_datetime`	`string`	ISO 8601 timestamp indicating when the consultation started.
`end_datetime`	`string`	ISO 8601 timestamp indicating when the consultation ended.
`report_status`	`string`	State of the report: `"intermediate"`, `"final"`, `"not_generated"` or `"purged"`. See Report status.
`generation_result`	`string`	Result of the report generation process. See Report generation result for possible values.
`generation_result_message`	`string`	User-friendly message providing more details about the report generation result. This is translated in the report output language and is intended to be shown to an end user.
`content_format`	`string \| null`	Whether the report’s text is plain text (`"plain"`) or rich text (`"markdown"`), or `null` when the consultation has no report. See Content format.
`data`	`Episode[] \| null`	The structured report content, or `null` when there is none. See Report status.

Report status

The report_status field describes the state of the consultation’s report. It is also the field that explains why data is null when it is.

`report_status`	`data`	Meaning
`final` / `intermediate`	`Episode[]`	A normal report. `intermediate` is a report for a consultation still in progress, `final` one for a finished consultation.
`final` / `intermediate`	`null`	The report exists, but produced no structured content. Questionnaire and custom-template reports do this when the transcript was too short to fill them in; `generation_result` says why.
`not_generated`	`null`	Generation never produced a report. It may still be running, or it may have failed.
`purged`	`null`	A report existed and was removed under the organization’s data retention policy.

data: null on its own does not mean there is no report. The second row above is a real report that happens to carry no structured content. Read report_status to tell the cases apart.

A report that generated normally but contains no episodes has data: [], not null.

A summary whose report_status is anything other than intermediate is the last one the consultation will produce, whether or not it carries content. It arrives on the summary-ready event and ends the recording.

View an example of a purged report


{
  "id": "yoEh163Y1cHih2S1",
  "input_language": "nl",
  "output_language": "nl",
  "start_datetime": "2025-01-01T12:00:00Z",
  "end_datetime": "2025-01-01T12:30:00Z",
  "report_status": "purged",
  "generation_result": "success",
  "content_format": "plain",
  "data": null
}

Content format

The content_format field says how to read the report’s text fields:

`content_format`	Meaning
`plain`	Plain text. Display it as is.
`markdown`	Rich text, written as Markdown. Render it with a Markdown renderer.
`null`	The consultation has no report (`report_status: "not_generated"`).

A report takes the format of the template it was generated from. Predefined templates are always plain; only custom templates can be rich text. Markdown is currently the only rich text format; more may be added later. A purged report keeps the format it had.

In TypeScript the field is typed as ContentFormat, exported from the SDK. Like report_status, it is an open union rather than a closed enum, so a format added after your installed SDK version still passes through. Fall back to plain text for a value you don’t recognize.


import type { ContentFormat } from '@squirehealth/sdk';
 
const renderers: Partial<Record<ContentFormat, (text: string) => string>> = {
  // Replace renderMarkdown with your actual Markdown rendering function
  markdown: renderMarkdown,
};
 
function renderReportText(text: string, format: ContentFormat | null | undefined) {
  // Plain text, and any format without a renderer, is shown as is
  const render = format ? renderers[format] : undefined;
  return render ? render(text) : text;
}

To support another format later, add a renderer for it.

Report generation result

The generation_result field indicates the outcome of the report generation process. The following values are possible:

Value	Report	Description
`success`	✓	Report was generated successfully.
`audio_quality_degraded`	⚠	A report was generated, but the audio quality was poor, which may have affected the accuracy of the report.
`transcript_too_short`	✗	The transcription was too short to generate a meaningful report.
`audio_too_short`	✗	The audio duration was too short to generate a report.
`no_medical_context`	✗	No medical context was detected in the consultation audio.

When the status is not success, the generation_result_message field provides a user-friendly explanation of the issue. Alternatively, you can use the generation_result code to display a localized message in your application.

When generation_result indicates a failure (e.g., transcript_too_short, audio_too_short, no_medical_context), the structured data may be empty or contain placeholder content.

Data structure

The API response contains metadata about the consultation, including the start and end time, the language of the input and output, and the structured data itself.

The structured data is organized into sections, each containing fields that represent different aspects of the consultation.

The data array contains the list of consultation episodes. Each episode has a template and a list of sections.

data is null whenever the response carries no report content, so check it before iterating. In TypeScript it is typed Episode[] | null, which surfaces the case at compile time.


const summary = await consultation.getSummary();
 
if (summary.data === null) {
  // No report content. `summary.report_status` says why.
  return;
}
 
for (const episode of summary.data) {
  // ...
}

Report status lists the cases in which data comes back null.

Templates

The Squire SDK supports different templates for generating structured data. The following templates are currently available:

Template Id	Description	Sections
`soap_new_complaint_api`	SOAP note for general practitioners	`subjective`, `objective`, `assessment`, `plan`
`soap_urgent_care_api`	SOAP note for GP urgent care consultations (out of hours service)	`subjective`, `objective`, `assessment`, `plan`
`specialist_general_api`	Contact note for specialist consultations. All sections have `summary` fields.	`reason_for_encounter`, `anamnesis`, `clinical_research`, `diagnosis`, `action_plan`, `conclusion`
`specialist_general_free_text_api`	Specialist contact note with all sections combined into a single free-text string.	`free_text`
`dictation_api`	Dictation session with the raw transcription.	`transcription`

Need a different structure? Create your own using templates.

Fields per section

Subjective

Field Id	Type	Description
`summary`	`object`	Summary of the section.
`medical_coding`	`array`	List of medical coding. (only included for `soap_urgent_care_api`)

Objective

Field Id	Type	Description
`summary`	`object`	Summary of the section.
`vital_signs`	`array`	List of vital signs.

Assessment

Field Id	Type	Description
`summary`	`object`	Summary of the section. (only included for `soap_urgent_care_api`)
`medical_coding`	`array`	List of medical coding.

Plan

Field Id	Type	Description
`summary`	`object`	Summary of the section.
`prescribed_medication`	`array`	List of prescribed medication.
`sick_note`	`object`	Sick note information.

Transcription

The transcription section is used in the dictation_api template and contains the following fields:

Field Id	Type	Description
`fixed`	`object`	The text that has been finalized.
`ongoing`	`object`	The ongoing transcription, which may still change as the user speaks.

Both fixed and ongoing fields have a text property, just like the summary field.

Fields

`summary`

Structure

Field Id	Type	Description
`text`	`string`	The textual summary of the section.

Example


{
  "summary": {
    "text": "Patient is feeling better."
  }
}

`vital_signs`

Structure

Field Id	Type	Description
`vital_sign_id`	`string`	The ID of the vital sign.
`unit`	`string`	The unit of the vital sign.
`value`	`number`	The value of the vital sign.

Available vital signs

Vital Sign ID	Unit	Description
`weight`	`kg`	Weight of the patient.
`height`	`cm`	Height of the patient.
`bmi`	`null`	Body Mass Index of the patient.
`systolic_blood_pressure`	`mmHg`	Systolic blood pressure of the patient.
`diastolic_blood_pressure`	`mmHg`	Diastolic blood pressure of the patient.
`heart_rate`	`bpm`	Heart rate of the patient.
`blood_glucose`	`mg/dL`	Blood glucose level of the patient.
`body_temperature`	`°C`	Body temperature of the patient.
`peak_flow`	`L/min`	Peak flow of the lungs.
`oxygen_saturation`	`%`	Oxygen saturation of the patient.

Example


{
  "vital_signs": [
    {
      "vital_sign_id": "systolic_blood_pressure",
      "unit": "mmHg",
      "value": 100.0
    },
    {
      "vital_sign_id": "diastolic_blood_pressure",
      "unit": "mmHg",
      "value": 60.0
    }
  ]
}

`medical_coding`

Structure

Field Id	Type	Description
`icd_10`	`string`	The ICD-10 code.
`icpc_2`	`string`	The ICPC-2 code.
`ibui`	`string`	The IBUI code.
`description`	`string`	The description of the diagnosis.

Example


{
  "medical_coding": [
    {
      "icd_10": "E61.1",
      "icpc_2": "T91",
      "ibui": "10024489",
      "description": "ijzerdeficiëntie"
    },
    {
      "icd_10": "M54.9",
      "icpc_2": "L02",
      "ibui": "10080680",
      "description": "rugpijn"
    }
  ]
}

`prescribed_medication`

Structure

Field Id	Type	Description
`active_ingredient`	`string`	The active ingredient of the medication.
`brand_name`	`string`	The brand name of the medication.
`pharmaceutical_form`	`string`	The pharmaceutical form of the medication.
`pack_size`	`string`	The pack size of the medication.
`atc_code`	`string`	The ATC code of the active ingredient.

Example


{
  "prescribed_medication": [
    {
      "active_ingredient": "Paracetamol",
      "brand_name": "Panadol",
      "pharmaceutical_form": "Tablet",
      "pack_size": "20",
      "atc_code": "N02BE01"
    }
  ]
}

`sick_note`

Structure

Field Id	Type	Description
`from_date`	`string`	The start date of the sick note. (in `YYYY-MM-DD` format)
`to_date`	`string`	The end date of the sick note. (in `YYYY-MM-DD` format)

Example


{
  "sick_note": {
    "from_date": "2025-01-01",
    "to_date": "2025-01-07"
  }
}