{ "openapi": "3.1.0", "info": { "title": "HelloSafe Travel Insurance API", "version": "1.0.0", "summary": "Price and sell travel insurance from any travel product.", "description": "A REST API that prices a trip against a multi-insurer travel insurance catalogue and returns comparable offers with their guarantees, then mints a tracked subscription link so the sale is attributed and paid as commission. Built for travel agencies, tour operators, OTAs, booking engines and travel apps that want to add travel insurance without becoming an insurer or holding a distribution licence.\n\nEvery key ships with a free sandbox that returns deterministic fixtures in the exact live response shape, so an integration can be built and tested end to end before a single insurer is called.\n\n**Authentication** is a per-caller HMAC-SHA256 handshake, server to server. Send three headers:\n\n- `x-atlas-key-id`: your key id\n- `x-atlas-timestamp`: unix seconds, rejected beyond a 5 minute window\n- `x-atlas-signature`: `v2=` + hex HMAC-SHA256 of `${timestamp}.${METHOD}.${pathname}.${rawBody}`, keyed with your signing secret\n\nThe signature covers the raw request body byte for byte. There is no CORS header on these responses: the signing secret must never reach a browser.", "termsOfService": "https://atlas.hellosafe.com/legal/terms", "contact": { "name": "HelloSafe Atlas", "url": "https://atlas.hellosafe.com/platform/api/documentation", "email": "atlas@hellosafe.com" }, "x-logo": { "url": "https://atlas.hellosafe.com/hellosafe-logo.svg" }, "x-providerName": "atlas.hellosafe.com", "x-apisguru-categories": [ "financial", "ecommerce" ], "license": { "name": "Proprietary", "url": "https://atlas.hellosafe.com/legal/terms" } }, "externalDocs": { "description": "Travel insurance API documentation", "url": "https://atlas.hellosafe.com/platform/api/documentation" }, "servers": [ { "url": "https://atlas.hellosafe.com", "description": "Production. Sandbox versus live is decided by your key, not by the URL." } ], "tags": [ { "name": "Quotes", "description": "Price a trip and read the catalogue vocabulary." }, { "name": "Links", "description": "Turn a chosen offer into a tracked, attributed subscription link." }, { "name": "Conversion", "description": "Server-to-server conversion postback." }, { "name": "Coach", "description": "Coverage gaps and ranked sell arguments from a traveller profile and a bank card." } ], "security": [ { "AtlasKeyId": [], "AtlasTimestamp": [], "AtlasSignature": [] } ], "paths": { "/api/v1/travel/meta": { "get": { "tags": [ "Quotes" ], "operationId": "getTravelMeta", "summary": "Reference data and key state", "description": "The vocabulary a caller would otherwise hard-code: the 15 trip types, the 26 funnel languages, the guarantee slugs with their English labels and groups, the guarantee states a response can carry, the request ceilings, and your key's own environment and quota. Does not consume quota.", "responses": { "200": { "description": "Reference data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/travel/quotes": { "post": { "tags": [ "Quotes" ], "operationId": "createTravelQuote", "summary": "Price a trip", "description": "Prices one trip against the travel catalogue and returns the priced offers, cheapest first, each with its premium, its guarantee ceilings and its policy documents. Read-only: nothing is stored, no subscription is created and no attribution happens here.\n\nEvery response also opens a quoting session: `sessionId` is a signed token identifying THIS traveller's flow, and POST /links requires it. To keep one traveller's session across a trip edit, echo the previous `sessionId` in the body — a valid one is returned unchanged, anything else silently starts a fresh session (a broken continuation never fails a pricing call). Never share one sessionId across travellers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "twoWeeksInThailand": { "summary": "One adult, two weeks in Thailand", "value": { "trip": { "intent": "forTourism", "startDate": "2026-09-10", "endDate": "2026-09-24", "countryResidence": "FR", "arrivalCountries": [ "TH" ], "travellers": [ { "age": 32 } ], "tripPrice": 1500, "currency": "EUR", "shouldCoverCancellation": false, "shouldCoverExtremeSports": false, "isAnnual": false }, "language": "en" } } } } } }, "responses": { "200": { "description": "Priced offers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded", "description": "Refused. QUOTA_EXCEEDED when the daily bucket is spent (Retry-After points at the next UTC day), RATE_LIMITED when more than 60 calls left in the current minute (Retry-After points at the next minute). Neither refusal is counted against your quota." }, "502": { "description": "Upstream pricing failed." }, "504": { "description": "Upstream pricing timed out." } } } }, "/api/v1/travel/links": { "post": { "tags": [ "Links" ], "operationId": "createTravelLink", "summary": "Mint a tracked subscription link", "description": "Turns a quoting session into the tracked link handed to the traveller. The first call of a session creates a quoting-stage subscription with your affiliate reference baked in server-side and returns the URL that resumes it; every later call of the SAME session returns the SAME subscription — a repeat offer click replays it (200, `replayed: true`), a changed trip updates it in place (`updated: true`), and a different session can never reach it, so two travellers with identical trips can never share a link. One exception protects the traveller: once they take the subscription past quoting (presubscribed, paid, subscribed), it is frozen, and the next call of the session rolls onto a fresh subscription (201, new subscriptionId) that the session follows from then on.\n\n`sessionId` is REQUIRED and comes from the POST /quotes response — a fabricated value fails its HMAC with BAD_SESSION_ID. Pass the `offerId` the traveller clicked to land them straight on the presubscribe form with that offer selected at the live re-rated premium (the funnel falls back to the offer list when the offer no longer prices); without it the link lands on the offer list.\n\nThe affiliate reference lives on the subscription rather than in a query string, so attribution survives a copy-paste through a messaging app, an email client and a browser redirect, and cannot be forged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkRequest" }, "examples": { "chosenOffer": { "summary": "The trip you just priced and the offer the traveller clicked", "value": { "sessionId": "qs_PASTE_THE_SESSION_FROM_YOUR_QUOTES_RESPONSE", "trip": { "intent": "forTourism", "startDate": "2026-09-10", "endDate": "2026-09-24", "countryResidence": "FR", "arrivalCountries": [ "TH" ], "travellers": [ { "age": 32 } ] }, "language": "en", "offerId": 900001 } } } } } }, "responses": { "200": { "description": "The session already holds its subscription: replayed (and updated in place when the trip changed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } } }, "201": { "description": "First mint of this session: the tracked link was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/QuotaExceeded", "description": "Refused. QUOTA_EXCEEDED when the daily bucket is spent (Retry-After points at the next UTC day), RATE_LIMITED when more than 60 calls left in the current minute (Retry-After points at the next minute). Neither refusal is counted against your quota." } } } }, "/api/v1/coach/bilan": { "post": { "tags": [ "Coach" ], "summary": "Coach bilan: coverage gaps and ranked sell arguments", "description": "Analyses a traveller's situation against the travel cover carried by their bank card, for the chosen destinations, and returns it as data: the card's GAPS (guarantees in default, adequately covered ones are omitted), a ranked list of arguments each with a strength and a category, the medical recommendation, a social-proof figure and an attributed quote link.\n\nSell-only by design: it returns the card's shortcomings, never a reason not to buy. Copy comes back as message KEYS plus interpolation variables, not finished sentences, so you render it in your own wording. Requires a key carrying the `coach` scope, which every self-serve key now has: the sandbox answers from the real engine, and its `offer.quoteUrl` comes back null because a sandbox key credits nobody.", "operationId": "postCoachBilan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "residence", "destinations" ], "properties": { "residence": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2. Drives the health socle and the default market.", "example": "FR" }, "destinations": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "example": [ "TH", "VN" ], "description": "Where they travel. ISO 3166-1 alpha-2, 1 to 50 codes." }, "card": { "type": "object", "description": "Exactly one card mode: { bin } | { bank, network, tier } | { catalogueId } | { network, tier } | { none: true }. A card that cannot be resolved never fails the call: it degrades to a baseline card and adds a code to meta.warnings.", "example": { "bin": "497010" } }, "trip": { "type": "object", "description": "Optional booleans, all default false.", "properties": { "friends": { "type": "boolean" }, "longTrip": { "type": "boolean" }, "riskyActivity": { "type": "boolean" } } }, "market": { "type": "string", "enum": [ "fr", "us", "ca", "sg", "my", "universal" ], "description": "Currency, formatting and health socle. Derived from residence when omitted." }, "ref": { "type": "string", "description": "Overrides the attribution ref baked into the returned quote URL." } } }, "examples": { "visaPremiumCard": { "summary": "A French traveller in Thailand, premium Visa card", "value": { "residence": "FR", "destinations": [ "TH" ], "card": { "bin": "497010" }, "trip": { "longTrip": true }, "market": "fr" } } } } } }, "responses": { "200": { "description": "The bilan. See the guide for the full field by field description.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "card": { "type": "object", "description": "origin (exact | generic | baseline | none), currency, detected issuer when a BIN resolved, and `guarantees`: the gaps only." }, "bilan": { "type": "object", "description": "shouldSell, headline, social proof, focusCategories, and `arguments` sorted by strength then category. Each argument carries messageKeys + vars, not prose." }, "destinations": { "type": "array", "items": { "type": "string" } }, "offer": { "type": "object", "description": "quoteUrl, carrying your attribution when the key is set up with it." }, "meta": { "type": "object", "description": "engineVersion, market, lang, passport and non-fatal warnings." } } } } } }, "400": { "description": "INVALID_JSON, BAD_RESIDENCE or NO_DESTINATIONS." }, "401": { "description": "UNAUTHORIZED, STALE_TIMESTAMP or INVALID_SIGNATURE." }, "403": { "description": "SCOPE_FORBIDDEN: the key lacks the coach scope." }, "502": { "description": "AUTH_LOOKUP_FAILED or CARD_RESOLVE_FAILED." } } } }, "/api/postback/conversion": { "post": { "tags": [ "Conversion" ], "operationId": "postConversion", "summary": "Report a conversion", "description": "Signed server-to-server postback that reports a sale against a tracked link. The short code is re-resolved to a real tracked link and the partner code is checked before any commission is recorded.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ref", "externalOrderId", "amount", "status" ], "properties": { "ref": { "type": "string", "description": "The tracked ref that carried the sale, partnerCode-shortCode.", "example": "ATL123-a1b2c3d4" }, "externalOrderId": { "type": "string", "description": "Your own order id. Replaying it updates that sale instead of creating a second one." }, "amount": { "type": "number", "description": "Premium paid by the traveller, in the sale currency." }, "commission": { "type": "number", "description": "Optional. Left out, it is computed server side from the configured rate." }, "currency": { "type": "string", "description": "ISO 4217. Defaults to EUR." }, "status": { "type": "string", "enum": [ "pending", "validated", "cancelled" ], "description": "State of the sale. A cancelled sale reverses the commission." } } }, "examples": { "validatedSale": { "summary": "A sale that just cleared", "value": { "ref": "ATL123-a1b2c3d4", "externalOrderId": "ORDER-123", "amount": 89.9, "commission": 44.95, "status": "validated" } } } } } }, "responses": { "200": { "description": "Conversion accepted." }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "AtlasKeyId": { "type": "apiKey", "in": "header", "name": "x-atlas-key-id", "description": "Your key id, from partners.api_clients." }, "AtlasTimestamp": { "type": "apiKey", "in": "header", "name": "x-atlas-timestamp", "description": "Unix seconds. Rejected beyond a 5 minute replay window." }, "AtlasSignature": { "type": "apiKey", "in": "header", "name": "x-atlas-signature", "description": "v2=." } }, "responses": { "BadRequest": { "description": "Malformed request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, expired or invalid signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key does not carry the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "QuotaExceeded": { "description": "Daily quota exhausted; resets at the next UTC midnight.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "examples": [ "UNAUTHORIZED", "BAD_LANGUAGE", "NO_TRAVELLERS", "TOO_MANY_TRAVELLERS", "QUOTA_EXCEEDED" ] } }, "required": [ "error" ] }, "Trip": { "type": "object", "required": [ "intent", "startDate", "endDate", "countryResidence", "arrivalCountries", "travellers" ], "properties": { "intent": { "type": "string", "description": "Trip type. `humanitarianAuPair` is still accepted and read as `humanitarian`.", "enum": [ "forTourism", "schengenArea", "annual", "studyInternship", "whv", "cruise", "digitalNomad", "expat", "groupTravel", "rentalStay", "mountainTrip", "backToHome", "humanitarian", "auPair", "toWork", "cancellation" ] }, "startDate": { "type": "string", "format": "date", "description": "First day of cover, YYYY-MM-DD." }, "endDate": { "type": "string", "format": "date", "description": "Last day of cover, YYYY-MM-DD. Never before startDate." }, "countryResidence": { "type": "string", "description": "ISO 3166-1 alpha-2.", "pattern": "^[A-Z]{2}$" }, "arrivalCountries": { "type": "array", "description": "ISO 3166-1 alpha-2, up to 20 destinations.", "maxItems": 20, "items": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "travellers": { "type": "array", "description": "One entry per traveller, up to 50. Above roughly 10 the individual products give way to the group product, which prices flat per head.", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "age" ], "properties": { "age": { "type": "integer", "minimum": 0, "maximum": 120 } } } }, "tripPrice": { "type": "number", "minimum": 0, "description": "Insured trip cost. Required when shouldCoverCancellation is true." }, "currency": { "type": "string", "description": "ISO 4217. The currency we price in, and the one tripPrice and studiesAmount are read in. Default EUR. Offers come back converted into it, using the same rate, margin and rounding as the subscription funnel and the card charge. A code we cannot convert into leaves offers in the insurer's own currency rather than failing the call: 33 codes are supported (USD, EUR, GBP, JPY, CNY, CHF, CAD, AUD, SEK, NOK, DKK, PLN, HUF, CZK, RON, BGN, RSD, ALL, MKD, BAM, BRL, MXN, MAD, ZAR, PHP, TRY, INR, HKD, SGD, AED, KRW, ISK, NZD).", "pattern": "^[A-Z]{3}$" }, "shouldCoverCancellation": { "type": "boolean", "default": false, "description": "Ask for cancellation cover. Requires tripPrice." }, "shouldCoverExtremeSports": { "type": "boolean", "default": false, "description": "Ask for extreme sports cover." }, "isAnnual": { "type": "boolean", "default": false, "description": "Forced true by the annual and expat trip types." } } }, "QuoteRequest": { "type": "object", "required": [ "trip" ], "properties": { "trip": { "$ref": "#/components/schemas/Trip", "description": "The trip to cover. Fields listed under The trip object below." }, "sessionId": { "type": "string", "description": "Optional: the sessionId from THIS traveller's previous /quotes response, to keep their session across a trip edit. A valid token is echoed back; anything else silently starts a fresh session. Never reuse one across travellers." }, "language": { "type": "string", "default": "en", "description": "Funnel language.", "enum": [ "bg", "cs", "da", "de", "el", "en", "es", "et", "fi", "fr", "hr", "hu", "is", "it", "lt", "lv", "mt", "nl", "no", "pl", "pt", "ro", "sk", "sl", "sv", "tr" ] } } }, "Offer": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "plan": { "type": [ "string", "null" ] }, "insurer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "logoUrl": { "type": [ "string", "null" ], "format": "uri" } } }, "price": { "type": "object", "properties": { "amount": { "type": "number", "description": "What the traveller pays. When the request carried a `currency` and conversion was possible, this is the converted amount, using the same rate, margin and rounding as the subscription funnel and the card charge. Display this value. Converting `insurerAmount` yourself will quote your customer less than they are charged." }, "amountInCents": { "type": "integer", "description": "`amount` in minor units of `currency`." }, "currency": { "type": "string", "description": "ISO 4217, uppercase. Equal to the requested `currency` when conversion happened.", "example": "AUD" }, "insurerAmount": { "type": "number", "description": "The insurer's own price, before conversion. Equal to `amount` when no conversion happened. For reconciliation, not for display." }, "insurerCurrency": { "type": "string", "description": "ISO 4217, uppercase. The currency the insurer prices in.", "example": "EUR" }, "isStartingPrice": { "type": "boolean", "description": "true = a from price; the exact premium is set in the funnel." }, "period": { "type": [ "string", "null" ] } } }, "guaranteeCurrency": { "type": "string", "description": "Currency the guarantee ceilings are expressed in." }, "guarantees": { "type": "object", "description": "Keyed by guarantee slug (see GET /api/v1/travel/meta).", "additionalProperties": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "value", "included", "actual_costs", "per_day", "return_ticket", "trip_price", "studies_amount", "not_available" ] }, "value": { "type": [ "number", "null" ] } } } }, "highlights": { "type": "object", "properties": { "included": { "type": "array", "items": { "type": "string" } }, "excluded": { "type": "array", "items": { "type": "string" } } } }, "documents": { "type": "object", "properties": { "cgvUrl": { "type": [ "string", "null" ], "format": "uri" }, "ipidUrl": { "type": [ "string", "null" ], "format": "uri" } } }, "position": { "type": "integer", "description": "Rank by premium, cheapest first." } } }, "QuoteResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "sessionId": { "type": "string", "description": "This traveller's quoting session, `qs_.`. Required by POST /links. Fresh on every response unless you echoed a valid one in." }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "unpricedCount": { "type": "integer", "description": "Catalogue offers that could not be priced for this trip." }, "redirectOnlyCount": { "type": "integer", "description": "Offers that matched and were priced but are deliberately NOT returned: the catalogue sells them by redirecting the traveller to the insurer's own site, so no subscription is created, the conversion postback never fires, and the sale could not be attributed or paid to you. Normally 0, because they are now excluded before we ever see them; a non-zero value means one slipped past that exclusion and our own filter caught it. Every offer you DO get back is one you can be paid on." }, "nearMissCount": { "type": "integer", "description": "Offers that would match if a filter were relaxed." }, "trip": { "$ref": "#/components/schemas/Trip" }, "quote": { "type": "object", "properties": { "mode": { "type": "string" }, "days": { "type": "integer" }, "travellers": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "meta": { "type": "object", "properties": { "apiVersion": { "type": "string" }, "language": { "type": "string" } } } } }, "LinkRequest": { "type": "object", "required": [ "sessionId", "trip" ], "properties": { "sessionId": { "type": "string", "description": "The traveller's quoting session, from the POST /quotes response. Required: one session = one traveller = one subscription. A fabricated value fails with BAD_SESSION_ID." }, "trip": { "$ref": "#/components/schemas/Trip", "description": "The trip to cover. Fields listed under The trip object below." }, "language": { "type": "string", "default": "en", "description": "Funnel language shown to the traveller. Default en." }, "offerId": { "type": "integer", "minimum": 1, "description": "The `id` of the /quotes offer the traveller clicked. The link then lands on the presubscribe form with that offer selected, re-rated live; omitted, it lands on the offer list." }, "linkCode": { "type": "string", "description": "One of your own tracked links, to split reporting by channel. A session's attribution is fixed by its first /links call." } } }, "LinkResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "subscriptionId": { "type": "string", "description": "Stable for the whole session while the traveller is still quoting; once they presubscribe or pay, the session rolls onto a fresh one." }, "url": { "type": "string", "format": "uri", "description": "Hand this to the traveller. With an offerId it lands on the presubscribe form with the offer selected; otherwise on the offer list. Attribution is attached either way." }, "ref": { "type": [ "string", "null" ], "description": "The affiliate reference baked into the subscription. Null in sandbox." }, "offerId": { "type": [ "integer", "null" ], "description": "Echo of the offer this response's url carries." }, "replayed": { "type": "boolean", "description": "True when the session already held its subscription (HTTP 200 instead of 201)." }, "updated": { "type": "boolean", "description": "True when this call changed the subscription's trip in place." }, "expiresAt": { "type": "string", "format": "date-time" }, "meta": { "type": "object" } } }, "MetaResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "apiVersion": { "type": "string" }, "key": { "type": "object", "properties": { "keyId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "quota": { "type": "object" }, "lifetime": { "type": "object" } } }, "trip": { "type": "object", "properties": { "intents": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "maxTravellers": { "type": "integer" }, "maxDestinations": { "type": "integer" }, "notes": { "type": "array", "items": { "type": "string" } } } }, "guarantees": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "label": { "type": "string" }, "group": { "type": "string" } } } }, "states": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string" }, "meaning": { "type": "string" } } } } } } } } }