HelloSafe Conversion API

openapi: 3.2.0
info:
  title: HelloSafe Travel Insurance Conversion API
  version: 2.3.2
  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.


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


    **Authentication** is a per-caller HMAC-SHA256 handshake, server to server. Send three headers:


    - `x-atlas-key-id`: your key id

    - `x-atlas-timestamp`: unix seconds, rejected beyond a 5 minute window

    - `x-atlas-signature`: `v2=` + hex HMAC-SHA256 of `${timestamp}.${METHOD}.${pathname}.${rawBody}`, keyed with your signing secret


    The 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
servers:
- url: https://atlas.hellosafe.com
  description: Production. Sandbox versus live is decided by your key, not by the URL.
security:
- AtlasKeyId: []
  AtlasTimestamp: []
  AtlasSignature: []
tags:
- name: Conversion
  description: Server-to-server conversion postback.
paths:
  /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.
                partnerFeeAmount:
                  type: number
                  description: 'Optional. The uplift slice of the handling fee you actually charged on this sale, in the sale currency. Declarative: the ledger recomputes what it should be from the partner''s own grid and pays the lower of the two, so this can only ever reduce what is owed, never inflate it. Leave it out when the offer carried no uplift.'
                contractVersion:
                  type: string
                  enum:
                  - '3.1'
                  - '3.2'
                  description: 'Optional. Which version of this contract you are speaking. Omitting it means 3.1, the shape that predates partnerFeeAmount, and stays valid. A version this endpoint does not know is refused with 400 UNKNOWN_CONTRACT_VERSION rather than parsed leniently: a field silently dropped here is a sale booked at the wrong price, and past the 14-day auto-validation that is no longer repairable.'
            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:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          examples:
          - UNAUTHORIZED
          - BAD_LANGUAGE
          - NO_TRAVELLERS
          - TOO_MANY_TRAVELLERS
          - QUOTA_EXCEEDED
      required:
      - error
  responses:
    Unauthorized:
      description: Missing, expired or invalid signature.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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=<hex HMAC-SHA256 of `${ts}.${METHOD}.${pathname}.${rawBody}`>.
externalDocs:
  description: Travel insurance API documentation
  url: https://atlas.hellosafe.com/platform/api/documentation
x-provenance:
  method: harvested
  publisher: HelloSafe
  source: https://atlas.hellosafe.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)