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:
| Type | Name | Description |
|---|---|---|
| 0 | Policy wording | The full terms and conditions of the cover. |
| 1 | Terms of business | The terms under which the product is distributed. |
| 2 | Marketing brochure | A summary or marketing description of the product. |
| 4 | Whitelabel policy wording | A distributor's own version of the policy wording. See Whitelabel documents. |
| 5 | IPID | Insurance Product Information Document: the standardised pre-contract summary required under the EU Insurance Distribution Directive (IDD). |
| 99 | Other | Any 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
| Attribute | How to use it |
|---|---|
name | The display title, already translated (e.g. "Policy Wording"). Use it as the link text. |
identifier | Unique per document. Use it to deduplicate. |
group_ident | Shared 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. |
language | The document's language code (e.g. en, fr, zh-cn). |
countries / country_divisions | Where the document applies. Both empty means it applies everywhere. |
owner_company_id | Empty for standard documents. Set for a distributor's own whitelabel documents. |
sort_order | Display in ascending order. |
url / file.original | The 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:
- Collect the documents of every product the traveller is looking at.
- Drop other distributors' documents: remove any document whose
owner_company_idis set and is not your own company id. - Group the documents by
group_ident. - For each group with a
group_ident, pick the variant that applies:- 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.
- 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.
- 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. - Deduplicate by
identifier. Documents are often shared between products, and in a tiered arrangement each tier carries its own copy of the same documents. - Sort by
sort_orderand display each one.
Example: one document in several languages
A product has a policy wording in three languages, all with
group_ident: "policy":
| identifier | group_ident | language | countries |
|---|---|---|---|
policy-en | policy | en | (none) |
policy-fr | policy | fr | (none) |
policy-de | policy | de | (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
| identifier | group_ident | language | countries | country_divisions |
|---|---|---|---|---|
tob-ca-en | tob | en | Canada | (none) |
tob-qc-fr | tob | fr | Canada | Quebec |
tob-qc-en | tob | en | Canada | Quebec |
- 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
nameas 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_documentsof theSubscription, which Sitata has already selected using these same rules.