Skip to main content

​
Overview

Use this page when you are ready to start integrating. It covers the protocol-level rules that apply before you move into the walkthrough and endpoint reference: authentication, versioning, payload shape, pagination, and date handling.

​
Security and authentication

Headout APIs are server-to-server APIs. Keep the API key on your backend, send every request over HTTPS, and do not call the APIs directly from a browser. Browsers are not supported for direct API calls because the platform does not support CORS for client-side access.
  • Authentication: send the Headout-Auth header on every request.
  • Obtaining keys: API keys are issued by Headout. There is no self-serve key portal — reach out to your Headout SPOC to obtain your sandbox and production keys.
  • Testing keys: use the sandbox key while you build and test.
  • Production keys: use the production key only after your integration is ready to launch.
Accept: application/json
Content-Type: application/json; charset=UTF-8
Headout-Auth: tk_your_testing_key
If the key is missing or invalid, the request fails before the business logic runs, so authentication should be the first thing you verify in your integration.

​
Environments

Headout APIs use separate hosts for sandbox and production. Build and validate in sandbox first, then switch to production when you are ready to launch.
  • Sandbox base URL: https://www.sandbox-headout.com
  • Production base URL: https://www.headout.com
The previous sandbox host https://sandbox.api.dev-headout.com will continue to work, so existing integrations are unaffected. We recommend migrating to https://www.sandbox-headout.com at your convenience.

​
Versioning and environments

Headout APIs are versioned. The version is part of the URL, and it tells the API which contract to use.
  • Versioning: use the versioned route for the endpoint family you are integrating with.
  • Sandbox: start in the sandbox and validate the full flow there first.
  • Production: move to production only after you have confirmed the integration in sandbox.
GET https://www.sandbox-headout.com/api/public/v2/products/
The same endpoint family uses the same versioned path in production, but production should only be used once your testing and launch checks are complete.

​
Payload format

Most Headout endpoints accept and return JSON. Keep the request payloads small and predictable, and always send the content headers that tell the API how to parse the body.
  • Request body: send JSON only.
  • Response body: expect JSON objects or JSON lists depending on the endpoint.
  • Headers: set Accept and Content-Type explicitly so the request and response format are unambiguous.
Accept: application/json
Content-Type: application/json; charset=UTF-8
When you build request payloads, keep field names exactly as defined by the endpoint. Field names are case-sensitive, and missing or misnamed fields usually trigger validation errors.

​
Pagination and responses

List endpoints return paginated responses. Use the pagination parameters to request the next slice of data instead of trying to fetch everything in one call. 
GET /api/public/v2/products/?offset=0&limit=100
A typical paginated response includes the current items plus the fields you need to continue. 
{
  "items": [],
  "nextUrl": "https://next-url",
  "prevUrl": "https://prev-url",
  "total": 100,
  "nextOffset": 20
}
  • Pagination: call the next page using the continuation data returned by the list response.
  • Response: use the response envelope to tell whether more pages are available. items carries the current page, nextUrl and nextOffset tell you how to fetch more, and prevUrl lets you move backwards if the API supports it.
  • Caching: do not treat inventory or other live list responses as static data.

​
Date formats

Headout APIs use two date formats:
  • ISO 8601: use this for fields such as startTime, endTime, dateCreated, and dateUpdated.
  • Localized format: use yyyy-MM-dd HH:mm:ss for timestamps that should be read in the supplier’s timezone, such as local-context tour start times.
{
  "startTime": "2026-04-10T09:30:00Z",
  "startTimeLocal": "2026-04-10 15:00:00"
}
When both formats are present for the same value, startTime in ISO 8601 takes precedence over startTimeLocal. Use the ISO value as the canonical timestamp when you parse, store, or compare dates, and use the localized value only when you need the supplier-local representation.

​
Postman collection

A Headout Partner API Postman collection is available on request via your Headout SPOC. Ask your SPOC to share it when you’re ready to test endpoints interactively.

​
Next step

Once these rules make sense, move on to the Integration walkthrough to see how they fit into the full booking flow.