Skip to main content

​
Terms of Service

The Headout API enables seamless integration with Headout’s platform, providing access to a wide range of functionalities, including querying availability, managing products, processing bookings, and much more.

​
Features

  • REST API: Simple and easy-to-use endpoints.
  • Supports JSON: For both requests and responses.
  • Data Model: A straightforward and intuitive data structure.
  • Security: Secured with SSL and API Key.
  • Performance: Fast and highly available, hosted on Amazon Web Services.

​
Do you need an API?

APIs are designed for developers. If you are not familiar with programming, we offer other solutions that may be easier to use. Headout provides a range of plugins for website integration, which do not require direct API usage. To learn more, check the integration plugins available in your Headout account.

​
Integration Partners

If you’re looking to build a new service around Headout’s platform, require additional APIs, or want Headout to directly integrate with your company’s software, reach out to our team to review your project and discuss feasibility.

​
Security

All requests to the Headout API must use HTTPS. If you attempt to use HTTP, the request will be automatically redirected to HTTPS with an HTTP Status 301 (Permanent Redirect). The API is not available on non-SSL/TLS ports, ensuring secure communication. We do not support Cross-Origin Resource Sharing (CORS), so REST calls to the Headout API should not be made directly from a browser. Instead, calls should be made server-to-server or through a secure environment. All API calls require a valid API Key for authentication. The API Key must be passed as an HTTP header in all requests: 
HTTP headers:
Headout-Auth: {api-token}
Example: 
Headout-Auth: pk_fgjsfg597sf7g5shsfhgf7hs7fg57s64sfg74h

​
Obtaining API Keys

To obtain your API Key, sign up on our Affiliate platform / Distributor platform, and you will receive your API keys via email. There are two types of API keys:
  • Production Keys: These are prefixed with pk_ and are valid only in the production environment. Use this key for all live production work.
  • Testing Keys: These are prefixed with tk_ and are valid only in the testing sandbox environment. Use this key for testing purposes.

​
Versioning

The Headout API is versioned, and you must include the version in the URL when making API calls. Our API is continuously updated within the same version with non-breaking changes, and the version number will be incremented only for major breaking changes. All Partner APIs are prefixed with /api/public/v{api_version}. For instance, if the API version is v2, the URL structure will be /api/public/v2. While V1 APIs, which previously followed the /api/v1 structure, will continue to work, it is recommended to transition to the new URL structure: /api/public/v1. Please refer to the changelog for detailed information on updates and changes. Currently, the Headout Product API is at version v2, while the Booking and Inventory APIs remain at version v1: 
GET https://www.headout.com/api/public/v2/products

POST https://www.headout.com/api/public/v1/booking

​
Environments

We have both Staging and Production environments. Use the Staging environment to test your integration before moving to the Production environment.
EnvironmentApplication URLAPI URL
Staginghttps://sandbox.deimos.dev-headout.comhttps://sandbox.api.dev-headout.com
Productionhttps://www.headout.comhttps://www.headout.com
Updates are typically released to the Staging environment about one week before they are deployed to Production. Therefore, there may be differences between these environments during that period.

​
Testing Sandbox

For testing your integration, use the sandbox environment available at https://sandbox.api.dev-headout.com. You will need to use the testing API key to access this environment. Keep your API key confidential and do not publish it in any publicly available repository or version control system, as this could expose your key to malicious bots frequently scanning for vulnerabilities.

​
Payload Format

​
Media Types

The Headout API supports JSON payloads encoded in UTF-8. It is essential to include both the Accept and Content-Type headers in your requests to ensure proper handling of the data: 
Content-Type: application/json; charset=UTF-8
Accept: application/json

​
Pagination

APIs that return multiple items are paginated by default. You can control the pagination using the offset and limit query parameters. For example: 
GET /products?offset=0&limit=100
GET /products?offset=100&limit=100
GET /products?offset=200&limit=100

​
Response

Pagination responses are wrapped with a pagination-wrapper. You can use the pagination wrapper to help with navigation along with getting to know other metadata about the current pagination. 
{
  "items": [],
  "nextUrl": "https://next-url",
  "prevUrl": "https://prev-url",
  "total": 100,
  "nextOffset": 20
}

​
Date Formats

There are two date formats used in the Headout API:
  • ISO 8601 Format: Typically used for fields such as startTime, endTime, dateCreated, and dateUpdated. This format is ideal for precise, timezone-aware timestamps. See ISO 8601.
  • Localized Format: Based on the supplier’s timezone setup on Headout, this format is displayed as yyyy-MM-dd HH:mm:ss and is often used for times that are relevant to the local context, such as tour start times.
When making API requests, you can choose to use either of these formats. If both are provided, the startTime (ISO 8601) will take precedence over startTimeLocal (Localized). See ISO 8601. By understanding these formats, you can ensure that your application correctly handles date and time data, whether it’s for global coordination or local relevance.