Unfortunately, the Heidi API and Widget are no longer available for future integrations in Australia and New Zealand. If you are a current Heidi customer looking to integrate, reach out to your Customer Success representative. Otherwise, contact our team to find out what this means for you.
Heidi API
Templates

Templates

Use consult-note templates when generating a session note (POST /sessions/{session_id}/consult-note). Use document templates when creating letters and other documents (POST /sessions/{session_id}/documents).

List consult-note templates

Method: GET

Path: /templates/consult-note-templates

Description: Return consult-note templates available to the linked user.

Request

GET /templates/consult-note-templates
Authorization: Bearer <your_token>

Query Parameters:

  • specialty_id (string, optional): Filter consult-note templates by specialty. If omitted, templates are resolved from the linked user.

Response

{
  "templates": [
    {
      "id": "659b8042fe093d6592b41ef7",
      "name": "H & P",
      "structure_template": "Template content...",
      "template_category": "CONSULT_NOTE_TEMPLATE",
      "template_html": "Template HTML content, if available...",
      "author_name": "Heidi"
    }
  ]
}

List document templates

Method: GET

Path: /templates/document-templates

Description: Return document templates (referral letters, certificates, and similar) available to the linked user.

Request

GET /templates/document-templates
Authorization: Bearer <your_token>

Query Parameters:

  • specialty_id (string, optional): Filter document templates by specialty. If omitted, templates are resolved from the linked user.

Response

{
  "templates": [
    {
      "id": "66455a5f0b0a1c8d018c6896",
      "name": "Letter back to referring clinician",
      "structure_template": "Template content...",
      "template_category": "DOCUMENT_TEMPLATE",
      "template_html": "Template HTML content, if available...",
      "author_name": "Heidi"
    }
  ]
}

Get a template by ID

Method: GET

Path: /templates/{template_id}

Description: Return a single consult-note or document template.

Request

GET /templates/659b8042fe093d6592b41ef7
Authorization: Bearer <your_token>

Response

{
  "id": "659b8042fe093d6592b41ef7",
  "name": "H & P",
  "structure_template": "Template content...",
  "template_category": "CONSULT_NOTE_TEMPLATE",
  "template_html": "Template HTML content, if available...",
  "author_name": "Heidi"
}

Set template section mappings

Method: PUT

Path: /templates/{template_id}/section-mappings

Description: Links each section of a consult-note template to a section ID in your EHR. When a note generated from the template is converted to a sectional note, each linked section is returned with its linked_ehr_section_id, so you know which EHR field to write it to.

A template's sections are the H1 headings in its structure_template: lines that start with a single # followed by a space (for example # Assessment). ## headings, bold text and plain lines are not sections.

You need write access to the template: you must own the personal template, or be an admin of the team or organisation that owns the team template. Heidi's built-in templates can be read but not mapped.

Request

PUT /templates/659b8042fe093d6592b41ef7/section-mappings
Authorization: Bearer <your_token>
Content-Type: application/json
 
{
  "section_mappings": [
    {
      "section_heading": "Reason for Referral",
      "linked_ehr_section_id": "reason_for_referral"
    },
    {
      "section_heading": "Assessment",
      "linked_ehr_section_id": "clinical_assessment"
    }
  ]
}

Request Fields:

  • section_mappings (array, required): The complete mapping for the template. Must contain at least one item.
    • section_heading (string, required): An H1 heading in the template. Matching is case-sensitive and ignores surrounding whitespace and Markdown emphasis, so **Plan** matches # Plan. The heading is stored without the emphasis.
    • linked_ehr_section_id (string, optional): The section ID in your EHR. Defaults to "", which leaves the section unlinked.

Mapping behaviour

  • Full replace: The saved mapping becomes exactly what you send. Any heading you leave out is unlinked. To change one section, fetch the current mapping with Get template section mappings, edit it and send the whole list back.
  • Clearing all mappings: section_mappings can't be empty, so send one heading with "" as its linked_ehr_section_id.
  • Renamed or removed headings: Saved headings that are no longer in the template are removed on the next PUT.
  • Repeated calls: Sending the same request again saves the same mapping. When calls overlap, the most recent PUT wins.

Who a mapping belongs to

Mappings are saved against the template and the user making the request. That user is the linked clinician if the token's identity is linked to a Heidi account, or your organisation's Open API user if it isn't. Set mappings with the same identity that will generate notes. If each clinician has their own copy of a template, each copy has its own template_id and needs its own mapping.

Response

The response lists every H1 heading in the template, in template order, with "" for headings that aren't linked.

{
  "template_id": "659b8042fe093d6592b41ef7",
  "section_mappings": [
    { "section_heading": "Reason for Referral", "linked_ehr_section_id": "reason_for_referral" },
    { "section_heading": "Clinical History", "linked_ehr_section_id": "" },
    { "section_heading": "Assessment", "linked_ehr_section_id": "clinical_assessment" },
    { "section_heading": "Recommendations", "linked_ehr_section_id": "" }
  ],
  "updated_at": "2026-09-18T12:00:00Z"
}

Response Fields:

  • template_id (string): The template the mapping belongs to.
  • section_mappings (array): One item per section heading, each with section_heading and linked_ehr_section_id.
  • updated_at (string): ISO 8601 timestamp of when the mapping was last saved.

Error responses

Returned with 400 Bad Request when a section_heading isn't an H1 heading in the template. valid_section_headings lists the headings you can use:

{
  "detail": {
    "type": "TemplateSectionMappingValidationError",
    "msg": "One or more section headings are not present in the template.",
    "valid_section_headings": [
      "Reason for Referral",
      "Clinical History",
      "Assessment",
      "Recommendations"
    ]
  }
}

The same error type, with the message "Duplicate section headings in request.", is returned when two items refer to the same heading after matching. A template with no H1 headings has nothing to map, so every PUT returns this error with an empty valid_section_headings list.

Returned with 400 Bad Request when the template doesn't exist or has been deleted:

{
  "detail": {
    "type": "TemplateNotFoundError",
    "msg": "Template not found."
  }
}

Returned with 403 Forbidden when you don't have write access to the template. The msg describes the reason:

{
  "detail": {
    "type": "TemplateAccessDeniedError",
    "msg": "User is not template owner."
  }
}

A malformed template_id or an empty section_mappings list returns 422 Unprocessable Entity.

Get template section mappings

Method: GET

Path: /templates/{template_id}/section-mappings

Description: Returns the saved section mapping for a template, in the same shape as the Set template section mappings response. You need read access to the template.

Request

GET /templates/659b8042fe093d6592b41ef7/section-mappings
Authorization: Bearer <your_token>

Response

{
  "template_id": "659b8042fe093d6592b41ef7",
  "section_mappings": [
    { "section_heading": "Reason for Referral", "linked_ehr_section_id": "reason_for_referral" },
    { "section_heading": "Clinical History", "linked_ehr_section_id": "" },
    { "section_heading": "Assessment", "linked_ehr_section_id": "clinical_assessment" },
    { "section_heading": "Recommendations", "linked_ehr_section_id": "" }
  ],
  "updated_at": "2026-09-18T12:00:00Z"
}

Every H1 heading in the template is listed in template order. If the template has changed since the mapping was saved, headings that are no longer in the template are listed after them, until the next PUT removes them.

Error responses

Returned with 404 Not Found when no mapping has been saved for this template by the user making the request:

{
  "detail": {
    "type": "TemplateSectionMappingNotFoundError",
    "msg": "Template section mapping not found."
  }
}

Returns 400 TemplateNotFoundError when the template doesn't exist or has been deleted, and 403 TemplateAccessDeniedError when you don't have read access.

AuthenticationPatient Profiles