Skip to main content

Displaying Product Documents

Every insurance product carries a list of product_documents: the policy wording, the Insurance Product Information Document (IPID), terms of business, brochures and any other disclosures the traveller must be able to read before they buy. This guide explains which documents to show, how to pick the right language and regional variant, and how to render them.

Why this matters

Showing the right documents before purchase is a regulatory requirement, not a nice-to-have. It is one of the items on the Pre-Launch Checklist, and Sitata reviews it before your integration goes live.

Where documents come from

Product documents are returned on each Product wherever products appear in the API, for example when you list products or request a quote. A single product often has many documents, because each document can exist in several languages and in different versions for different countries or regions.

After a purchase, each Subscription also has a product_documents list. That list has already been filtered by Sitata for the traveller's country, region and language, so after a purchase you can display it as-is (for example on a confirmation page or in your own emails). The selection logic below is only needed before purchase, when you work from the raw product data.

Document types

Each document has a numeric type:

TypeNameDescription
0Policy wordingThe full terms and conditions of the cover.
1Terms of businessThe terms under which the product is distributed.
2Marketing brochureA summary or marketing description of the product.
4Whitelabel policy wordingA distributor's own version of the policy wording. See Whitelabel documents.
5IPIDInsurance Product Information Document: the standardised pre-contract summary required under the EU Insurance Distribution Directive (IDD).
99OtherAny other required disclosure.

Type 3 is reserved. New types may be added in future, so your integration must not depend on a fixed list.

Never filter by type

Show every applicable document, whatever its type. Do not build a display that only shows "the policy wording" or that skips types it does not recognise: an IPID or regulatory disclosure that you leave out is a compliance failure. Use type only for styling or icons, if you need it at all.

Key attributes

AttributeHow to use it
nameThe display title, already translated (e.g. "Policy Wording"). Use it as the link text.
identifierUnique per document. Use it to deduplicate.
group_identShared by all variants of the same document (e.g. its English and French versions, or its Ontario and Quebec versions). Show one document from each group.
languageThe document's language code (e.g. en, fr, zh-cn).
countries / country_divisionsWhere the document applies. Both empty means it applies everywhere.
owner_company_idEmpty for standard documents. Set for a distributor's own whitelabel documents.
sort_orderDisplay in ascending order.
url / file.originalThe link to the document. Use url when it is set (an externally hosted document), otherwise file.original.

Choosing which documents to display

To decide what one traveller sees, you need their country, their region (state or province, an ISO 3166-2 subdivision code) and their language. Use the same values you send when you purchase. Then:

  1. Collect the documents of every product the traveller is looking at.
  2. Drop other distributors' documents: remove any document whose owner_company_id is set and is not your own company id.
  3. Group the documents by group_ident.
  4. For each group with a group_ident, pick the variant that applies:
    1. Location: keep the documents for the traveller's region. If there are none, keep the documents for their country (and no particular region). If there are none, keep the documents with no countries or regions.
    2. Language: among those, keep the documents in the traveller's language. If there are none, keep the English ones. If there are no English ones either, keep whatever is left.
  5. For documents with no group_ident: each one is a standalone document, not a variant of another. Apply the language step (4.2) to these documents as one set.
  6. Deduplicate by identifier. Documents are often shared between products, and in a tiered arrangement each tier carries its own copy of the same documents.
  7. Sort by sort_order and display each one.

Example: one document in several languages

A product has a policy wording in three languages, all with group_ident: "policy":

identifiergroup_identlanguagecountries
policy-enpolicyen(none)
policy-frpolicyfr(none)
policy-depolicyde(none)
  • A French-speaking traveller sees only policy-fr.
  • A Spanish-speaking traveller sees policy-en, because there is no Spanish version and English is the fallback.
  • Nobody sees all three. Listing every language variant side by side is the most common display mistake.

Example: regional and language variants

identifiergroup_identlanguagecountriescountry_divisions
tob-ca-entobenCanada(none)
tob-qc-frtobfrCanadaQuebec
tob-qc-entobenCanadaQuebec
  • A French-speaking traveller in Quebec sees tob-qc-fr.
  • An English-speaking traveller in Quebec sees tob-qc-en. The regional variant takes priority over the country-wide one.
  • A French-speaking traveller in Ontario sees tob-ca-en. No Ontario-specific version exists, so the country-wide one applies, and English is the fallback because it has no French variant.

Matching language codes

Compare language codes case-insensitively, and treat _ and - the same (pt_BR = pt-br). For Chinese, compare by script: zh, zh-cn and zh-Hans are all Simplified Chinese, while zh-tw, zh-hk, zh-mo and zh-Hant are all Traditional Chinese. Never give a Traditional Chinese reader a Simplified document as "their" language. Fall back to English instead.

Example implementation

function normalizeLang(code) {
const c = (code || '').toLowerCase().replace(/_/g, '-')
if (!c.startsWith('zh')) return c
return ['zh-tw', 'zh-hk', 'zh-mo'].includes(c) || c.includes('hant')
? 'zh-hant'
: 'zh-hans'
}

function byLanguage(docs, lang) {
const target = normalizeLang(lang)
const exact = docs.filter((d) => normalizeLang(d.language) === target)
if (exact.length) return exact
const english = docs.filter((d) => normalizeLang(d.language) === 'en')
if (english.length) return english
return docs
}

function byLocation(docs, countryCode, regionCode) {
const region = docs.filter((d) =>
d.country_divisions.some((cd) => cd.iso_a2 === regionCode))
if (regionCode && region.length) return region

const country = docs.filter((d) =>
!d.country_divisions.length &&
d.countries.some((c) => c.country_code === countryCode))
if (countryCode && country.length) return country

return docs.filter((d) => !d.countries.length && !d.country_divisions.length)
}

// products: the products being displayed (e.g. every tier in a tiered set)
// myCompanyId: your company id, or null
function documentsToDisplay(products, { countryCode, regionCode, lang, myCompanyId }) {
const docs = products
.flatMap((p) => p.product_documents)
.filter((d) => !d.owner_company_id || d.owner_company_id === myCompanyId)

const groups = {}
const ungrouped = []
docs.forEach((d) => {
if (d.group_ident) (groups[d.group_ident] ||= []).push(d)
else ungrouped.push(d)
})

const picked = byLanguage(ungrouped, lang)
Object.values(groups).forEach((variants) => {
const mine = variants.filter((d) => myCompanyId && d.owner_company_id === myCompanyId)
const standard = variants.filter((d) => !d.owner_company_id)
const ownPick = mine.length ? byLanguage(byLocation(mine, countryCode, regionCode), lang) : []
picked.push(...(ownPick.length
? ownPick
: byLanguage(byLocation(standard, countryCode, regionCode), lang)))
})

const unique = [...new Map(picked.map((d) => [d.identifier, d])).values()]
return unique.sort((a, b) => a.sort_order - b.sort_order)
}

// Rendering: one link per document, titled with its name
// <a href={doc.url || doc.file.original} target="_blank">{doc.name}</a>

Whitelabel documents

If Sitata has set up your own version of a document, for example your own policy wording, it is returned with owner_company_id set to your company id (policy wording of this kind has type: 4). The API also returns other distributors' whitelabel documents. Always remove those (step 2 above).

  • Within a group (same group_ident): your own document replaces the standard one, as long as one of your variants matches the traveller's location and language. If none of yours applies to that traveller, use the standard document instead, so the traveller is never left without one.
  • Without a group: your own documents are shown in addition to the standard ones.

Display requirements

  • Show the documents next to the product display, before purchase: on the same screen as the price and the purchase action, not only after purchase or in an email.
  • Make every document downloadable or openable, with its name as the link text.
  • Design for several documents: your sandbox products may have only one, but production products often have four or more.
  • In a tiered arrangement, list the documents once for the whole set (deduplicated by identifier) rather than repeating them for each tier.
  • Link to the documents the API serves. Do not download, re-host or cache copies: document URLs are refreshed by the API, and a stale copy can misstate coverage.
  • After purchase, use the product_documents of the Subscription, which Sitata has already selected using these same rules.