Links

Mint a tracked subscription link

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.

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.

The 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.

With a sandbox key (ak_test_), no real subscription is created, so there is nothing for the link to resume. subscriptionId is a placeholder (sub_sandbox_...), ref is null, and url opens the HelloSafe quote form with only the residence country, destinations, number of travellers and trip intent prefilled: never the dates or the ages, and never the subscription step, even when you pass an offerId. The prefilled subscription step (/travel-insurance/app/subscribe?subscription_id=...&offerId=...) only exists with a live key (ak_live_).

Warning: the sandbox link opens the real hellosafe.com funnel. There is no test card and no sandbox checkout, so any payment made through a sandbox link is a real purchase with a real card. Testing the payment step end to end means making a real purchase through a link minted with your live key.

post/api/v1/travel/links

Request

  • Base URL: https://atlas.hellosafe.com
  • URL: https://atlas.hellosafe.com/api/v1/travel/links
  • 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

sessionIdstring required

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.

languagestring

Funnel language shown to the traveller. Default en.

offerIdinteger

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.

linkCodestring

One of your own tracked links, to split reporting by channel. A session's attribution is fixed by its first /links call.

Example request

{
  "trip": {
    "stateResidence": "NY"
  }
}

Response

The session already holds its subscription: replayed (and updated in place when the trip changed).

okboolean
mode'sandbox' | 'live'
subscriptionIdstring

Stable for the whole session while the traveller is still quoting; once they presubscribe or pay, the session rolls onto a fresh one. In sandbox, a placeholder (sub_sandbox_...): no subscription exists behind it.

urlstring uri

Hand this to the traveller, as it comes. Live key: a tracked short link (https://atlas.hellosafe.com/r/<code>?quote=..&offer=..) that counts each click on your link in the dashboard, then opens the quote: with an offerId, the presubscribe form with the offer selected; otherwise the offer list. Attribution lives on the quote, so it holds either way, and the redirect still lands on the quote if the click cannot be counted. Sandbox key: it opens the real hellosafe.com quote form with residence, destinations, traveller count and intent prefilled (never dates or ages), credits nothing, and any payment made through it is real.

refstring nullable

The affiliate reference baked into the subscription. Null in sandbox.

offerIdinteger nullable

Echo of the offer this response's url carries.

replayedboolean

True when the session already held its subscription (HTTP 200 instead of 201).

updatedboolean

True when this call changed the subscription's trip in place.

expiresAtstring date-time
metaobject

Changes

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