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: your sandbox key is available on the Headout partner portal. Production keys are issued by Headout and cannot be generated from the portal. To request one, email partnerships@headout.com and copy your Headout SPOC if you have one.
  • 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.
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.The sandbox environment has an expected daily downtime of up to 5 minutes between 2:00 AM and 3:00 AM IST for database maintenance. API requests during this window may fail. Plan any automated testing or scheduled jobs accordingly.

​
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.
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.
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.
A typical paginated response includes the current items plus the fields you need to continue.
  • 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.
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.

​
Rate limits

Some endpoints cap how many requests you can send within a time window. When you go over a limit, the API responds with 429 Too Many Requests and a retry-after header telling you how many seconds to wait before retrying.
  • Create Booking is limited to 100 requests per rolling 30-minute window per API key (sliding window), on both v1 and v2. The limit counts every request that reaches the endpoint — successful (200) and failed (e.g. 400, 5xx) alike. Requests already rejected with 429 do not count toward the window.
  • On a 429, read the retry-after header (the number of seconds to wait) and schedule your retry instead of polling blindly. The error body (error.code = E_RATE_LIMIT_EXCEEDED) repeats the wait time in a human-readable form.
See Create a new booking for the full 429 response shape and the retry-after header.

​
Postman collection

There is no maintained Postman collection today. Treat the curl examples on each endpoint page as the source of truth for request shape, headers, and query parameters. To work with these endpoints in Postman or another API client, import the curl commands directly — most tools (including Postman) support pasting a curl command to generate a request. You can also convert a curl command or an OpenAPI spec into a Postman collection using AI-assisted tools such as Claude, or by connecting an MCP-based workflow to your API client.

​
Next step

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