Documentation

Part one

Get started

From nothing to priced offers in one afternoon. Every snippet below runs as it is once you drop your own key in. One key opens every endpoint on this page.

Step 0

What you need

This is a server to server API. There is no CORS header on any response, on purpose: a signing secret that reaches a browser is a secret you have to revoke.

Step 1

Get your sandbox key

Create a partner account, open API in the dashboard, and click Create my test key. You get a key id and a signing secret on the spot. Nobody reviews anything, because a sandbox key is inert: it answers from fixed sample data, calls no insurer, creates no real quote and credits no sale.

Sandbox quota: 200 prices and 50 links per day, and 60 calls per minute whatever the endpoint. The daily figure is what an integration day needs; the per minute ceiling is what stops a runaway loop.

Step 2

Sign a request

Three headers on every call:

`${ts}.${METHOD}.${pathname}.${rawBody}`

e.g.  1787654321.POST./api/v1/travel/quotes.{"trip":{...},"language":"en"}

Step 3

Your first priced quote

One call describes one trip: dates, destinations, ages. You get the offers that cover it, sorted cheapest first, each with its price and the detail of every guarantee.

Node.js

import { createHmac } from "node:crypto";

const KEY_ID = process.env.ATLAS_KEY_ID;        // ak_test_... (sandbox)
const SECRET = process.env.ATLAS_SIGNING_SECRET; // shown once, at creation

const body = JSON.stringify({
  trip: {
    intent: "forTourism",
    startDate: "2026-09-10",
    endDate: "2026-09-24",
    countryResidence: "FR",
    arrivalCountries: ["TH"],
    travellers: [{ age: 32 }]
  },
  language: "en"
});

const ts = Math.floor(Date.now() / 1000).toString();
const sig = "v2=" + createHmac("sha256", SECRET)
  .update(`${ts}.POST./api/v1/travel/quotes.${body}`)
  .digest("hex");

const res = await fetch("https://atlas.hellosafe.com/api/v1/travel/quotes", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-atlas-key-id": KEY_ID,
    "x-atlas-timestamp": ts,
    "x-atlas-signature": sig
  },
  body
});

const { sessionId, offers } = await res.json();
console.log(offers.length, "offers, cheapest:", offers[0].price.amount);
// Keep sessionId next to what you display: it is THIS traveller's quoting
// session, and /links will require it.

cURL

KEY_ID="ak_test_..."
SECRET="sk_test_..."
BODY='{"trip":{"intent":"forTourism","startDate":"2026-09-10","endDate":"2026-09-24","countryResidence":"FR","arrivalCountries":["TH"],"travellers":[{"age":32}]},"language":"en"}'
TS=$(date +%s)
SIG="v2=$(printf '%s.POST./api/v1/travel/quotes.%s' "$TS" "$BODY" \
  | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)"

curl -s https://atlas.hellosafe.com/api/v1/travel/quotes \
  -H "content-type: application/json" \
  -H "x-atlas-key-id: $KEY_ID" \
  -H "x-atlas-timestamp: $TS" \
  -H "x-atlas-signature: $SIG" \
  -d "$BODY"

PHP

<?php
$keyId  = getenv('ATLAS_KEY_ID');
$secret = getenv('ATLAS_SIGNING_SECRET');
$path   = '/api/v1/travel/quotes';

$body = json_encode([
  'trip' => [
    'intent'           => 'forTourism',
    'startDate'        => '2026-09-10',
    'endDate'          => '2026-09-24',
    'countryResidence' => 'FR',
    'arrivalCountries' => ['TH'],
    'travellers'       => [['age' => 32]],
  ],
  'language' => 'en',
]);

$ts  = (string) time();
$sig = 'v2=' . hash_hmac('sha256', "$ts.POST.$path.$body", $secret);

$ch = curl_init('https://atlas.hellosafe.com' . $path);
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => $body,          // the SAME string you signed
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => [
    'content-type: application/json',
    "x-atlas-key-id: $keyId",
    "x-atlas-timestamp: $ts",
    "x-atlas-signature: $sig",
  ],
]);
$response = json_decode(curl_exec($ch), true);
echo count($response['offers']), " offers\n";

What comes back

{
  "ok": true,
  "mode": "sandbox",
  "sessionId": "qs_1f2e3d4c5b6a79880919a2b3c4d5e6f7.9a8b…",
  "offers": [
    {
      "id": 9001,
      "name": "Sandbox Essential",
      "plan": "Essential",
      "insurer": { "name": "Sandbox Assurance", "logoUrl": null },
      "price": {
        "amount": 38.40,
        "amountInCents": 3840,
        "currency": "EUR",
        "insurerAmount": 38.40,
        "insurerCurrency": "EUR",
        "isStartingPrice": false,
        "period": null
      },
      "guaranteeCurrency": "EUR",
      "guarantees": {
        "hospitalFeesAbroad": { "state": "value", "value": 100000 },
        "rapatriationAssistance": { "state": "actual_costs" },
        "suitcaseInsurance": { "state": "value", "value": 1000 },
        "cancelTrip": { "state": "not_available" }
      },
      "highlights": { "included": ["..."], "excluded": ["..."] },
      "documents": { "cgvUrl": null, "ipidUrl": null },
      "position": 1
    }
  ],
  "unpricedCount": 0,
  "redirectOnlyCount": 0,
  "trip": { "...": "the trip we priced, normalised" },
  "quote": {
    "mode": "sandbox",
    "days": 15,
    "travellers": 1,
    "expiresAt": "2026-09-01T12:30:00.000Z"
  },
  "meta": { "apiVersion": "1.0.0", "language": "en", "notice": "Sandbox data..." }
}

Full field by field description in the reference below. The live response has the same shape, with real insurers and real premiums.

insurer.logoUrl is the offer's pictogram now, not the insurer's logo. This changed in 2.0.0. Our own comparator stopped showing insurer logos on brokerage offers: each offer carries its own icon, a pictogram on a tile. The API follows, and it follows in the field you are already reading, so your page shows the new image with no change on your side. The name is a misnomer and we kept it deliberately, so that the switch reaches you without work. The image is an SVG served by the very function that draws it on hellosafe.com, so what you display is what our own visitors see. Add ?size=16..512 if your layout wants another size: it is vector, so any size stays sharp.

The insurer is still named. insurer.name is untouched, so "underwritten by Chapka" keeps working, which is what your customer needs to know. What is no longer published, for an offer that has an icon, is that insurer's logo.

iconUrl tells you which of the two you got. It carries the same URL as logoUrl when the offer has an icon, and is absent, never null and never an empty string, when it has none, in which case logoUrl fell back to the insurer's logo. Reading logoUrl alone can no longer tell those apart. Every offer we serve carries an icon today, so the fallback is not hit in practice, but the sandbox's cheapest plan deliberately has none, which is why you cannot see the field in the response above: code that path before you go live rather than after.

redirectOnlyCount is the offers we deliberately do not return. The catalogue also carries offers sold by sending the traveller to the insurer's own site. Those cannot be attributed to you: the sale leaves HelloSafe, no subscription exists, the conversion postback never fires and you would not be paid. They are also a dead end for the traveller, who would have to key the whole trip in again. The count is normally 0: they are 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.

Step 4

Turn a chosen offer into a sale

When the traveller picks an offer, ask for a link with the sessionId your quote came with and the offerId they clicked. It creates the quote on the HelloSafe side with your attribution baked in, and returns the URL you hand over: the traveller lands on the presubscribe form with their offer selected at the live premium, finishes and pays in the HelloSafe funnel, and the commission is yours.

const path = "/api/v1/travel/links";
const body = JSON.stringify({
  sessionId,            // from the /quotes response: the traveller's session
  trip,                 // same trip you priced
  language: "en",
  offerId: chosen.id    // the offer they clicked, from the /quotes offers
});

const ts = Math.floor(Date.now() / 1000).toString();
const sig = "v2=" + createHmac("sha256", SECRET)
  .update(`${ts}.POST.${path}.${body}`)
  .digest("hex");

const res = await fetch("https://atlas.hellosafe.com" + path, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-atlas-key-id": KEY_ID,
    "x-atlas-timestamp": ts,
    "x-atlas-signature": sig
  },
  body
});

const { url, subscriptionId } = await res.json();
// -> https://hellosafe.com/travel-insurance/app/subscribe
//        ?subscription_id=...&offerId=...
// Hand that URL to the traveller: they land on the presubscribe form with
// their offer selected, premium re-rated live. The sale is credited to you.
// Click another offer? Call again with the SAME sessionId: same subscription,
// new offer in the URL. Trip edited? Same sessionId: updated in place.

In sandbox this returns a prefilled funnel link that credits nothing. Never show a sandbox price or a sandbox link to a real traveller.

Try it

Run every endpoint, right here

Paste a sandbox key and send a real signed request to each endpoint. The request is signed in your browser and answered by the live sandbox - no install, no server, nothing billed or credited. Each endpoint carries its schema, a Node snippet and the exact curl, so you can copy what worked.

Prefer your own client? Download the Postman collection: set your sandbox key once and every request signs itself, and the Quotes request saves its sessionId so Links works on the next click. In the playground below, run Quotes first and paste its sessionId into the Links body.

Step 5

Go live

Live access is a short review. It is not a sales threshold: we size your daily quota against the traffic you expect, and we record who presents the guarantees to the traveller, which is the question a regulator would ask us.

The checklist turns green on its own in your dashboard, and the application asks for your expected volume, your markets and your distribution status. Approval sets your quotas; you then create the live key yourself, so the signing secret is never seen by anyone at HelloSafe.

Going live gives you a second key, not a promoted one. Your sandbox key stays alive with its own quota, so your tests keep running against fixtures after production traffic starts. The only thing that changes in your code is the pair of credentials it reads from the environment.

Good to know

The five things that go wrong

Every error code, with its HTTP status, is listed in the error table. The machine readable contract is openapi.json.

Part two

Endpoints

Generated from the spec, version 2.3.0, so what you read here is what the API answers.

Quotes

Price a trip and read the catalogue vocabulary. This is what most integrations use.

Links

Turn a chosen offer into a tracked link that credits the sale to you.

Coach

What a traveller's bank card does not cover, and the arguments that sell the gap.

Conversion

Report a sale you took yourself, so it can be commissioned.

Environments

Sandbox and live

The URL never changes. The key decides.

The response shape is identical in both, deliberately: an integration built against the sandbox runs unchanged in production. Start at the quickstart above.

Authentication

Signed requests

Signature scheme

v2   `${ts}.${METHOD}.${pathname}.${rawBody}`

# GET has an empty body, so the message simply ends on the dot:
v2   `${ts}.GET./api/v1/travel/meta.`

v2 binds the signature to the endpoint it was minted for. Under v1 a captured signature replayed on any other route of the same API, since only the body was covered. That is why v1 is retired: a v1 signature answers 401 V1_SCHEME_RETIRED.

Rotating your secret

Rotating issues a new signing secret and keeps the previous one working for 24 more hours, so you can deploy through a normal release instead of scheduling downtime. The dashboard shows the deadline until the window closes. Revoking is different: it stops the key, and the old secret with it, immediately. That is the path to use if a secret has leaked.

Shared payload

The trip object

Used by /quotes and /links alike. tripInfo is accepted as an alias for trip.

The ceilings are deliberate: one call describes one trip, not a customer file.

Trip types

Vocabulary

Prices and currency

price.amount is what the traveller pays. Send a currency in the trip and we convert with the same rate, the same conversion margin and the same rounding the subscription funnel displays and the card is charged, so the figure you show and the figure we debit are the same one.

price.insurerAmount and price.insurerCurrency are the insurer's own price, before conversion. They are there for reconciliation. Converting them yourself is the one mistake to avoid: your rate is not ours, so your customer is quoted less than they are charged and finds out at the payment screen. When no conversion happened the two amounts are equal, so displaying amount is always correct.

Currency codes are uppercase on every field.

Your own rate

A partner can set their own commission from their dashboard, between the base rate their account carries and 50%. Everything above the base rate is funded by raising the handling fee on the policy, so the traveller pays the difference, and it applies on every channel: tracked links, the widget, and this API.

price.amount already includes it. It is still what the traveller pays and still what the card is charged, so nothing about the rule above changes. When you charge an uplift, the response also carries meta.partnerFee with feeBps (the whole handling fee inside those prices), upliftBps (your share of it) and commissionBps (what a sale pays you), in basis points of the insurer premium. It is a breakdown, never an amount to add on top. Without an uplift the object is simply absent.

The rate is frozen onto each sale when the conversion is booked, so moving it never rewrites what an earlier sale paid.

Vocabulary

Guarantees

offer.guarantees maps a slug to a state and, when the state carries a ceiling, a value. Ceilings are expressed in guaranteeCurrency, which is not always the price currency.

Slugs

Labels are English. Localise them on your side, or read the live list from GET /api/v1/travel/meta, which is the authority as the catalogue grows. Treat an unknown slug as a forward compatible addition rather than an error.

No key needed

Embed, without writing a line of code

Not every integration needs an API. The Marketplace embed puts the whole HelloSafe comparator on your page with one script tag: the visitor compares, subscribes and pays without leaving you, and the sale is credited to your account.

<div id="hellosafe-widget"></div>
<script src="https://atlas.hellosafe.com/widget.js"
        data-ref="YOUR-TRACKING-CODE"
        data-intent="forTourism"
        data-residence="FR"
        data-lang="en"
        data-height="900"></script>

Your own snippet, with your tracking code and your defaults already filled in, is generated in the dashboard under Widget. It carries the trip type, the residence country and the language you choose, and each configuration gets its own tracked link so your reporting stays split by page or campaign.

Limits

Quotas

Two ceilings, and they do different jobs. The daily buckets bound what a key does over a day: reads are the pricing and Coach calls, writes are the minted links, capped much lower because one link is one traveller. The burst ceiling bounds one minute, all endpoints together, and it is what actually stops a runaway loop: a daily cap only notices once the damage is done.

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 173
X-RateLimit-Reset: 41230           # seconds until the daily bucket rolls
X-RateLimit-Burst-Remaining: 57    # calls left in the current minute

Over the daily cap you get 429 with QUOTA_EXCEEDED, the bucket name and Retry-After. Over the minute you get 429 with RATE_LIMITED and a Retry-After of a few seconds. Neither refused call is counted against you, and being throttled never costs you a day: on a burst refusal the daily headers keep describing the day, so X-RateLimit-Remaining is what is still yours once the minute rolls, not zero.

Reading the headers beats discovering the ceiling: they are on every answer, including the Coach.

Edge cases

Errors

The body is a JSON object with an error field carrying the code below, sometimes with a detail field beside it.

Good to know

Versioning and terms

The path is versioned. Structured fields are stable; new guarantee slugs, trip types and offers can appear, so treat unknown values as forward compatible additions. What an integration accepts: no reselling or redistribution of the prices, no long lived caching of a premium, insurer name and documents stay attached to the offer you display, no real personal data in the sandbox, and server to server only. A secret in a browser bundle is a revoked key.

Ready to build? Back to the quickstart · Get a free sandbox key · openapi.json