Coach

Coach bilan: coverage gaps and ranked sell arguments

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.

Sell-only by design: it returns the card's shortcomings, never a reason not to buy, except bilan.medical, which gives the trip's recommended medical ceiling (it follows the destination) and whether the card meets it. 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.

post/api/v1/coach/bilan

Request

  • Base URL: https://atlas.hellosafe.com
  • URL: https://atlas.hellosafe.com/api/v1/coach/bilan
  • Auth: API key in header x-atlas-key-id and API key in header x-atlas-timestamp and API key in header x-atlas-signature

Request body

residencestring required

ISO 3166-1 alpha-2. Drives the health socle and the default market.

destinationsstring[] required

Where they travel. ISO 3166-1 alpha-2, 1 to 50 codes.

cardobject

Exactly one card mode: { catalogueId } | { bin } | { bank, network, tier } | { network, tier } | { none: true }. catalogueId names the exact card: take it from GET /api/v1/coach/cards (a sandbox key identifies cards by BIN or bank instead, see key.cardModes there). A BIN or { bank, network, tier } match by range: at a bank with two cards of one tier, the most basic one wins. A card that cannot be resolved never fails the call: it degrades to a baseline card and adds a code to meta.warnings.

market'fr' | 'us' | 'ca' | 'sg' | 'my' | 'universal'

Currency, formatting and health socle. Derived from residence when omitted.

refstring

Overrides the attribution ref baked into the returned quote URL.

Example request

{
  "residence": "FR",
  "destinations": [
    "TH",
    "VN"
  ],
  "card": {
    "bin": "497010"
  }
}

Response

The bilan. See the guide for the full field by field description.

okboolean
cardobject

origin (exact | generic | baseline | none), currency, detected issuer when a BIN resolved, and guarantees: the gaps only.

bilanobject

shouldSell, headline, medical (the trip's recommended medical ceiling, from 30 000 € inside the traveller's health zone to 500 000 € for the United States, and ceilingOk), social proof, focusCategories, and arguments sorted by strength then category. Each argument carries messageKeys + vars, not prose.

destinationsstring[]
offerobject

quoteUrl, carrying your attribution when the key is set up with it: a tracked short link (https://atlas.hellosafe.com/r/<code>?res=..&lang=..) that counts each click in your dashboard's Links tab, then opens the HelloSafe travel form. Display it as it comes.

metaobject

engineVersion, market, lang, passport and non-fatal warnings.

Changes

No recorded changes to this operation across all 1 revision of this API.