> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squire.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize Consultation Output with Templates

> Define the structure of Squire's consultation output using built-in templates or custom schemas. Map report fields directly to your EHR's data model.

Templates control the shape of the data Squire returns after each consultation. By defining a template, you tell Squire which fields to extract and how to structure the output — so you can map it directly to your EHR's data model without additional transformation.

<Note>
  Passing `templateSchema` directly in `startRecording` is new in SDK v1.6.0. If you are on an earlier version, use the API approach described below.
</Note>

## Two ways to use templates

You can provide a template to Squire either server-side via the API or client-side via the SDK.

<Steps>
  <Step title="Choose your approach">
    Use the **API approach** if you manage templates centrally on your server and want to reuse them across multiple clients. Use the **SDK approach** if you need to define or update templates dynamically at the point of recording.
  </Step>

  <Step title="Create or pass the template">
    <Tabs>
      <Tab title="Via API (server-side)">
        Create and store the template by posting to the Template API on your server. Once created, pass the returned template ID when starting a recording:

        ```javascript theme={null}
        await client.startRecording({ templateId: 'your-template-id' });
        ```
      </Tab>

      <Tab title="Via SDK (client-side)">
        Pass the template schema directly in `startRecording`. Squire creates the template if it does not exist, or updates it if it does:

        ```javascript theme={null}
        await client.startRecording({
          templateId: 'your-template-id',
          templateSchema: schema,
        });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Receive structured output">
    Listen for the `summary-ready` event and process the returned data using the `Template` utility class. See [Processing results](#processing-results) below.
  </Step>
</Steps>

<Tip>
  Always provide a `templateId` string when passing `templateSchema`. This can be any string — for example, your own internal ID. The ID appears in the Squire Portal, which makes templates easier to identify and debug.
</Tip>

## Template schema

A template schema is an object with a `fields` array. Each field defines one piece of data Squire should extract from the consultation.

### Field properties

| Property       | Required           | Description                                                                          |
| -------------- | ------------------ | ------------------------------------------------------------------------------------ |
| `id`           | Yes                | Unique identifier for the field (e.g., `"symptoms_start"`).                          |
| `name`         | Yes                | Human-readable display name (e.g., `"Onset Date"`).                                  |
| `valueType`    | Yes                | Data type of the expected value. One of: `text`, `options`, `date`, `boolean`.       |
| `valueOptions` | For `options` type | Array of `{ value: string, description?: string }` objects defining allowed choices. |
| `description`  | No                 | Additional context or unit information to improve extraction accuracy.               |
| `fields`       | No                 | Array of nested fields. Use this when values are related to each other.              |

### Field types

| Type      | Description                                  |
| --------- | -------------------------------------------- |
| `text`    | Free text output.                            |
| `options` | Fixed choices, as defined in `valueOptions`. |
| `date`    | Date value in `YYYY-MM-DD` format.           |
| `boolean` | `true` or `false` output.                    |

### Schema example

```javascript theme={null}
const schema = {
  fields: [
    {
      id: 'symptoms_start',
      name: 'Onset Date',
      valueType: 'date',
      description: 'First occurrence of symptoms'
    },
    {
      id: 'severity',
      name: 'Severity',
      valueType: 'options',
      valueOptions: [
        { value: 'mild', description: 'Mild' },
        { value: 'moderate', description: 'Moderate' },
        { value: 'severe', description: 'Severe' }
      ]
    },
    {
      id: 'has_allergies',
      name: 'Has allergies?',
      valueType: 'boolean',
      description: 'Does the patient have any allergies?',
      fields: [
        {
          id: 'allergy_details',
          name: 'Allergy details',
          valueType: 'text',
          description: 'If yes, specify the allergens (e.g., pollen, peanuts, medications)'
        }
      ]
    }
  ]
};
```

## Processing results

When the `summary-ready` event fires, use the `Template` utility class to extract field values from the response without manually traversing the data structure.

```javascript theme={null}
client.on('summary-ready', (summary) => {
  if (summary.data) {
    // Create a Template instance from the API response
    const template = Squire.Template.fromResponse(summary.data);

    // Get all field values as a flat Record<id, value>
    const values = template.getFieldValues();
    console.log(values['severity']);

    // Or get a specific field by ID, including nested fields
    const severityField = template.getFieldById('severity');
    console.log(severityField?.value);
  }
});
```

### Template utility methods

| Method                                   | Description                                                                         |
| ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `Squire.Template.fromResponse(response)` | Creates a `Template` instance from the API response data.                           |
| `template.getFieldValues()`              | Returns a flat `Record<id, value>` map of all field IDs and their extracted values. |
| `template.getFieldById(id)`              | Searches for a specific field by ID, including fields nested inside other fields.   |