Gets travel-insurance quotes from HelloSafe for a trip: priced offers from HelloSafe partners, shown in a comparison widget. Required: countryResidence, arrivalCountries (not for an annual multi-trip cover, which is worldwide), traveller ages, the trip length as endDate or durationDays (not for an annual or expat cover, which runs a year), and stateResidence for a US resident. Every other field has a default. The trip length is not defaulted: a wrong length gives a wrong price. HelloSafe is a licensed insurance broker, paid a commission by the insurers whose policies it distributes.
View input schema
{
"type": "object",
"properties": {
"locale": {
"description": "Language the user is writing in, as a BCP 47 tag or 2-letter code (e.g. \"fr\", \"pt-BR\"): the widget and all offer texts are localized with it, so when it is set the quote follows the user's language even if it differs from the app UI. When it is absent, the host UI locale is used if the host provides one (not every host does), then English; the quote never depends on a host locale being present.",
"type": "string"
},
"subscriptionId": {
"description": "Existing subscription ID to update instead of creating a new one.",
"type": "string"
},
"cardId": {
"description": "HelloSafe card ID returned by check_card_coverage, for a user who holds a credit card with travel cover: offers are then re-ranked by how well they fill that card's coverage gaps, and each offer lists what it adds over the card (complementsCard).",
"type": "number"
},
"displayCurrency": {
"description": "ISO 4217 code of a display currency other than the trip-cost currency. Without it, amounts are shown in the trip-cost currency.",
"type": "string"
},
"requiredCoverages": {
"description": "Optional filter on policy features, the guarantee filters of the HelloSafe comparison site: only the offers whose contract includes every listed cover are returned, that cover listed first. maternityCover = covers pregnancy; preExistingConditionsCover = covers pre-existing medical conditions; personalLiability; baggage; travelDelay; directHospitalBilling = the insurer pays the hospital directly; disability; searchAndRescue; earlyReturn; tripInterruption; electronics = electronic devices; cashAdvance; expatMaternity, expatDental, expatOptical (expatriates). Each trip purpose has its own filters, as on the site; a cover that is not one of them is ignored and reported. Used when the user asks for a policy that includes this cover; it changes neither prices nor eligibility, and health-related covers are not stored.",
"type": "array",
"items": {
"type": "string",
"enum": [
"maternityCover",
"preExistingConditionsCover",
"personalLiability",
"baggage",
"travelDelay",
"directHospitalBilling",
"disability",
"searchAndRescue",
"earlyReturn",
"tripInterruption",
"electronics",
"cashAdvance",
"expatMaternity",
"expatDental",
"expatOptical"
]
}
},
"cancelForAnyReason": {
"description": "Cancel For Any Reason option, like trip cancellation: an add-on bought with the policy (extra cost, a purchase window counted from the first trip payment, usually 75 % of prepaid costs refunded). Sold to US residents only, on a forTourism, cruise or cancellation trip; true keeps the offers that sell it. Defaults to false.",
"type": "boolean"
},
"tripInfo": {
"description": "Trip details.",
"type": "object",
"properties": {
"intent": {
"description": "Trip purpose. Leisure, holidays, sightseeing, a business trip, a visit back home or a rental stay → \"forTourism\"; study abroad, Erasmus, internship → \"studyInternship\"; working-holiday visa (PVT) → \"whv\"; yearly multi-trip cover → \"annual\"; long-term relocation → \"expat\"; cancellation-only (no medical) → \"cancellation\"; ski / trek / mountaineering → \"forTourism\" with the extreme sports option; cruise → \"cruise\"; remote-work nomading → \"digitalNomad\"; group of 10+ travellers → \"groupTravel\"; Schengen visa application → \"schengenArea\"; humanitarian mission or volunteering → \"humanitarian\"; au pair placement → \"auPair\". The purpose decides which policies are offered: a wrong one gives offers built for another trip. Defaults to \"forTourism\". \"annual\" and \"expat\" set isAnnual=true.",
"type": "string",
"enum": [
"forTourism",
"schengenArea",
"annual",
"studyInternship",
"whv",
"cruise",
"digitalNomad",
"expat",
"groupTravel",
"humanitarian",
"auPair",
"cancellation"
]
},
"countryResidence": {
"description": "User's country of residence as ISO 3166-1 alpha-2 code (e.g. \"FR\"). It decides which insurers can cover the traveller; it cannot be deduced from the destination or the conversation language.",
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"stateResidence": {
"description": "State of residence as its USPS 2-letter code (e.g. \"CA\", \"TX\"). Required for a US resident: US travel insurance is regulated state by state, and no quote is computed without it. Ignored for every other country. The US territories are countries here, not states (a Puerto Rico resident is countryResidence \"PR\", never \"US\" + \"PR\").",
"type": "string",
"pattern": "^[A-Za-z]{2}$"
},
"arrivalCountries": {
"description": "Destination countries as ISO 3166-1 alpha-2 codes, as an array ([\"TH\",\"VN\"]) or a comma-separated string. \"WW\" = the whole world (forTourism, cruise, digitalNomad); \"SCH\" = the whole Schengen area (schengenArea). Required, except for intent \"annual\": a yearly multi-trip cover is worldwide and uses no destination.",
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"pattern": "^([A-Za-z]{2}|SCH|sch)$"
}
},
{
"type": "string"
}
]
},
"travellers": {
"description": "All travellers covered by the policy, including children. Example: a couple aged 35 with a 5-year-old → [{age:35},{age:35},{age:5}].",
"type": "array",
"items": {
"type": "object",
"properties": {
"age": {
"description": "Age in years, 0–99.",
"type": "number"
}
},
"required": [
"age"
]
}
},
"startDate": {
"description": "Trip start date (YYYY-MM-DD). Defaults to tomorrow when omitted.",
"type": "string"
},
"endDate": {
"description": "Trip end date (YYYY-MM-DD). The quote needs the trip length: endDate or durationDays (not for an annual or expat cover, which runs a year). It comes from the dates or duration given and is not defaulted, because a wrong length gives a wrong price.",
"type": "string"
},
"durationDays": {
"description": "Trip length in whole days; the server computes endDate = startDate + durationDays. One of durationDays or endDate gives the trip length (not for an annual or expat cover). It is not defaulted: a wrong length gives a wrong price.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"tripPrice": {
"description": "TOTAL trip cost for ALL travellers (not per traveller). Only used by cancellation coverage.",
"type": "number"
},
"currency": {
"description": "ISO 4217 code for tripPrice. Defaults to the currency of countryResidence.",
"type": "string"
},
"shouldCoverCancellation": {
"description": "Include trip cancellation coverage. Defaults to false.",
"type": "boolean"
},
"shouldCoverExtremeSports": {
"description": "Extreme sports option (mountaineering, off-piste skiing, diving, paragliding, climbing), added to the policy at extra cost like trip cancellation. Defaults to false; only relevant when the trip includes such activities.",
"type": "boolean"
},
"isAnnual": {
"description": "Annual / multi-trip cover. Defaults to false (auto-true for intent=\"annual\" or \"expat\").",
"type": "boolean"
},
"studiesInterruption": {
"description": "Cover interrupted studies (intent=\"studyInternship\" only). Defaults to false. Requires studiesAmount when true.",
"type": "boolean"
},
"studiesAmount": {
"description": "Tuition fees to cover, in tripInfo.currency. Required when studiesInterruption=true.",
"type": "number"
},
"tripBoughtDate": {
"description": "Date the trip was booked (YYYY-MM-DD). Required when shouldCoverCancellation=true (most insurers require booking within ~30 days).",
"type": "string"
}
},
"required": [
"countryResidence",
"travellers"
]
}
},
"required": [
"tripInfo"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}