--- title: "Mint a tracked subscription link" method: POST path: "/api/v1/travel/links" tags: ["Links"] --- # Mint a tracked subscription link `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` 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. ## Request body - LinkRequest - `sessionId` string, 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. - `trip` Trip, required - `intent` 'forTourism' | 'schengenArea' | 'annual' | 'studyInternship' | 'whv' | 'cruise' | 'digitalNomad' | 'expat' | 'groupTravel' | 'rentalStay' | 'mountainTrip' | 'backToHome' | 'humanitarian' | 'auPair' | 'toWork' | 'cancellation', required: Trip type. `humanitarianAuPair` is still accepted and read as `humanitarian`. - `startDate` string, date, required: First day of cover, YYYY-MM-DD. - `endDate` string, date, required: Last day of cover, YYYY-MM-DD. Never before startDate. - `countryResidence` string, required: ISO 3166-1 alpha-2. - `stateResidence` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY': US residents only: the state they live in, as its USPS code (one of the 50 states or DC, also listed by GET /meta as trip.usStates). US travel insurance is regulated state by state, so `US` alone does not identify a resident. Optional, and it prices nothing: the offers and premiums are the same with or without it. It is echoed in the priced `trip`, and POST /links stores it on the subscription. Read only when countryResidence is `US` and dropped for any other residence; for a US resident, any other value is refused with BAD_STATE_RESIDENCE. The five US territories are countries, not states: a Puerto Rico resident is countryResidence `PR` with no stateResidence, and the same goes for GU, VI, AS and MP. - `arrivalCountries` string[], required: ISO 3166-1 alpha-2, up to 20 destinations. - `travellers` object[], required: One entry per traveller, up to 50. Above roughly 10 the individual products give way to the group product, which prices flat per head. - `age` integer, required - `tripPrice` number: Insured trip cost: the total price of the trip for the whole party, not a per-traveller amount. Required when shouldCoverCancellation is true. - `currency` string: 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). - `shouldCoverCancellation` boolean: Ask for cancellation cover. Requires tripPrice. - `shouldCoverExtremeSports` boolean: Ask for extreme sports cover. - `isAnnual` boolean: Forced true by the annual and expat trip types. - `language` string: Funnel language shown to the traveller. Default en. - `offerId` integer: 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` string: One of your own tracked links, to split reporting by channel. A session's attribution is fixed by its first /links call. ## Response `200` The session already holds its subscription: replayed (and updated in place when the trip changed). - LinkResponse - `ok` boolean - `mode` 'sandbox' | 'live' - `subscriptionId` string: 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. - `url` string, uri: Hand this to the traveller, as it comes. Live key: a tracked short link (https://atlas.hellosafe.com/r/?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. - `ref` string, nullable: The affiliate reference baked into the subscription. Null in sandbox. - `offerId` integer, nullable: Echo of the offer this response's url carries. - `replayed` boolean: True when the session already held its subscription (HTTP 200 instead of 201). - `updated` boolean: True when this call changed the subscription's trip in place. - `expiresAt` string, date-time - `meta` object ## Other responses - `201`: First mint of this session: the tracked link was created. - `400`: Malformed request. - `401`: Missing, expired or invalid signature. - `403`: The key does not carry the required scope. - `429`: Daily quota exhausted; resets at the next UTC midnight. --- [API](https://skmtc.dev/hellosafe/apis/hellosafe-travel-insurance-api.md) · [All operations](https://skmtc.dev/hellosafe/apis/hellosafe-travel-insurance-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hellosafe/apis/hellosafe-travel-insurance-api/revisions/8185e81c9817?raw)