You’re looking at the old docs. The new (and better) one lives here:  https://partner.headout.com/docs
logo
API docs by Redocly

Headout API (1.0.0)

Download OpenAPI specification:

Introduction

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.

Getting Started

Headout API Partners

Headout offers different API products for various business needs. Make sure to choose the right one for your specific use case.

Headout API for Affiliates

Affiliates using the Headout API will primarily interact with product, category, subcategory, collection, and city APIs to access the necessary data for their platforms. Please note that affiliates will not require access to booking and inventory APIs, as these are more relevant for other types of partners.

The available APIs for affiliates include:

  • Product API: Allows access to detailed product information, including pricing, descriptions, media, and availability across different cities.
  • Category API: Enables retrieval of product categories, helping to organize and display products efficiently.
  • Subcategory API: Provides information on subcategories related to specific products, allowing for more granular classification.
  • Collection API: Offers access to curated collections of products, which can be displayed as themed or seasonal offers.
  • City API: Facilitates access to city-specific data, like Headout supported cities.

By focusing on these APIs, affiliates can seamlessly integrate Headout's offerings into their platforms, ensuring accurate and up-to-date information for their users.

Headout API for Booking Partners

Integration Walkthrough and Checklist Document

API partners using the Headout API will have access to the full suite of available APIs, enabling comprehensive integration with Headout's platform. This includes access to products, categories, subcategories, collections, cities, bookings, and inventory management.

The available APIs for API partners include:

  • Product API: Allows access to detailed product information, including pricing, descriptions, media, and availability across different cities.
  • Category API: Enables retrieval of product categories, helping to organize and display products efficiently.
  • Subcategory API: Provides information on subcategories related to specific products, allowing for more granular classification.
  • Collection API: Offers access to curated collections of products, which can be displayed as themed or seasonal offers.
  • City API: Facilitates access to city-specific data, like Headout supported cities.
  • Booking API: Enables the creation, retrieval, and management of bookings, making it essential for partners who need to handle reservations directly through their systems.
  • Inventory API: Provides access to real-time inventory data for specific products and variants, ensuring accurate availability information for users.

API partners can utilize this comprehensive set of APIs to fully integrate Headout’s offerings into their own platforms, enabling seamless transactions, accurate data management, and enhanced user experiences.

How to use these APIs?

Flow

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.

Environment API URL
Staging https://sandbox.api.dev-headout.com
Production https://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:

  • ISO8601 Format: Typically used for fields such as startTime, endTime, dateCreated, and dateUpdated. This format is ideal for precise, timezone-aware timestamps.

  • 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 (ISO8601) will take precedence over startTimeLocal (Localized).

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.

Booking

Booking operations

Create a new booking

POST /booking

Create a new booking object in UNCAPTURED state.

The booking creation and acceptance flow is a 2 step flow. Calling this API creates the initial booking in UNCAPTURED state and returns back the same booking along with the new booking id. You should call this API before fulfilling the booking flow on your end. Once you get a response, you can then fulfill the booking flow on your end and then call PUT /booking to capture the booking and start the fulfillment process of the booking on our end.

If the booking capturing doesn't happen within an hour then the booking status is automatically changed to CAPTURE_TIMEOUT.

Request

Request Example 
{
  "productId": "5678",
  "variantId": "1234",
  "inventoryId": "1455",
  "customersDetails": {
    "count": 3,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "value": "a@b.com"
          }
        ]
      }
    ]
  },
  "price": {
    "amount": 100,
    "currencyCode": "USD"
  }
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": null,
  "variantId": "1234",
  "startDateTime": "2017-04-12T19:30:00",
  "product": {
    "id": "2832",
    "name": "Aladdin",
    "variant": {
      "id": "4384",
      "name": "Grand Circle"
    }
  },
  "customersDetails": {
    "count": 3,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Name",
            "value": "a@b.com"
          }
        ]
      }
    ]
  },
  "seatInfo": [
    {
      "section": "A",
      "row": "10",
      "seatNumber": "12",
      "seatCode": "A-10-12"
    }
  ],
  "price": {
    "amount": 100,
    "currencyCode": "USD"
  },
  "status": "CAPTURE_TIMEOUT",
  "voucherUrl": "https://www.headout.com/voucher/126890?key=AAAD6AAAABhsDVGlVXsL2YDAf65qMsOQAlqJZdsw80eczQCIL6sa5rITsvOjxoD5NwaoBDiwlEY%3D",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ],
  "creationTimestamp": 1491902295
}

Notes

  • All bookings start in UNCAPTURED status and must be captured within 1 hour via PUT /booking/{id}
  • The price.amount and price.currencyCode in the response may differ from the request if currency conversion occurs
  • tickets array is typically empty/null for new bookings and populated after fulfillment
  • voucherUrl provides immediate access to booking information even before tickets are generated
  • seatInfo is only populated for seatmap-enabled bookings
  • bookingId represents the itinerary identifier in the system
  • variantId represents the variant (tour) identifier that was booked
Authorizations:
apiKeyAuth
Request Body schema: application/json
required
productId
string

ID of the product which the variant is part of.

variantId
string

ID of the variant to be booked.
inventoryId
string

ID of the inventory to be booked.
object

Details of the customers.
object

Pricing details for the booking.

Responses

Request samples

Content type
application/json
{
  • "productId": "string",
  • "variantId": "string",
  • "inventoryId": "string",
  • "customersDetails": {
    },
  • "price": {
    }
}

Response samples

Content type
application/json
{
  • "bookingId": "string",
  • "partnerReferenceId": "string",
  • "variantId": "string",
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "customersDetails": {
    },
  • "seatInfo": [
    ],
  • "price": {
    },
  • "status": "UNCAPTURED",
  • "voucherUrl": "string",
  • "tickets": [
    ],
  • "creationTimestamp": 0
}

Fetch all bookings

GET /booking

Retrieve a list of all Bookings.

Response Example 
{
    "items": [{
        "bookingId": "126890",
        "partnerReferenceId": "AX67873DDFSR",
        "variantId": "1234",
        "startDateTime": "2017-04-12T19:30:00",
        "product": {
            "id": "2832",
            "name": "Aladdin",
            "variant": {
                "id": "4384",
                "name": "Grand Circle"
            }
        },
        "customersDetails": {
            "count": 3,
            "customers": [{
                "personType": "ADULT",
                "isPrimary": true,
                "inputFields": [{
                    "id": "EMAIL",
                    "name": "Name",
                    "value": "a@b.com"  
                }]
            }]  
        },
        "seatInfo": [
            {
                "section": "A",
                "row": "10",
                "seatNumber": "12",
                "seatCode": "A-10-12"
            }
        ],
        "price": {
            "amount": 100,
            "currencyCode": "USD"
        },
        "status": "CAPTURE_TIMEOUT",
        "voucherUrl": "https://www.headout.com/voucher/126890?key=AAAD6AAAABhsDVGlVXsL2YDAf65qMsOQAlqJZdsw80eczQCIL6sa5rITsvOjxoD5NwaoBDiwlEY%3D",
        "tickets": [
        {
            "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
            "url": null,
            "type": "QRCODE"
        }],
        "creationTimestamp": 1491902295

    }],
    "nextUrl": "https://www.headout.com/api/public/v1/booking?offset=1&limit=1",
    "prevUrl": null,
    "total": 100,
    "nextOffset": 1
}
Authorizations:
apiKeyAuth

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v1/booking' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

Fetch a booking by ID

GET /booking/{id}

Retrieve details of a specific Booking by its ID.

Request

MODE KEY TYPE OPTIONAL DESCRIPTION
PATH id string no The booking id.

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "1234",
  "startDateTime": "2017-04-12T19:30:00",
  "product": {
    "id": "2832",
    "name": "Aladdin",
    "variant": {
      "id": "4384",
      "name": "Grand Circle"
    }
  },
  "customersDetails": {
    "count": 3,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Name",
            "value": "a@b.com"
          }
        ]
      }
    ]
  },
  "seatInfo": [
    {
      "section": "A",
      "row": "10",
      "seatNumber": "12",
      "seatCode": "A-10-12"
    }
  ],
  "price": {
    "amount": 100,
    "currencyCode": "USD"
  },
  "status": "CAPTURE_TIMEOUT",
  "voucherUrl": "https://www.headout.com/voucher/126890?key=AAAD6AAAABhsDVGlVXsL2YDAf65qMsOQAlqJZdsw80eczQCIL6sa5rITsvOjxoD5NwaoBDiwlEY%3D",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ],
  "creationTimestamp": 1491902295
}
Authorizations:
apiKeyAuth
path Parameters
id
required
string

ID of the booking to fetch.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v1/booking/<some-booking-id>' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "bookingId": "string",
  • "partnerReferenceId": "string",
  • "variantId": "string",
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "customersDetails": {
    },
  • "seatInfo": [
    ],
  • "price": {
    },
  • "status": "UNCAPTURED",
  • "voucherUrl": "string",
  • "tickets": [
    ],
  • "creationTimestamp": 0
}

Update a booking

PUT /booking/{id}

Used to modify a booking. Currently this is only used for capturing the booking and assigning a partnerReferenceId. Use this method to capture the booking by specifying the status as PENDING. The booking will be fulfilled on our end only once you capture it.

Request

Request Example 
{
  "status": "PENDING",
  "partnerReferenceId": "AX67873DDFSR"
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "1234",
  "startDateTime": "2017-04-12T19:30:00",
  "product": {
    "id": "2832",
    "name": "Aladdin",
    "variant": {
      "id": "4384",
      "name": "Grand Circle"
    }
  },
  "customersDetails": {
    "count": 3,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Name",
            "value": "a@b.com"
          }
        ]
      }
    ]
  },
  "seatInfo": [
    {
      "section": "A",
      "row": "10",
      "seatNumber": "12",
      "seatCode": "A-10-12"
    }
  ],
  "price": {
    "amount": 100,
    "currencyCode": "USD"
  },
  "status": "PENDING",
  "voucherUrl": "https://www.headout.com/voucher/126890?key=AAAD6AAAABhsDVGlVXsL2YDAf65qMsOQAlqJZdsw80eczQCIL6sa5rITsvOjxoD5NwaoBDiwlEY%3D",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ],
  "creationTimestamp": 1491902295
}
Authorizations:
apiKeyAuth
path Parameters
id
required
string

ID of the booking to update.
Request Body schema: application/json
required
status
string
Enum: "PENDING" "UNCAPTURED" "COMPLETED" "CANCELLED" "FAILED"

Updated status of the booking.
partnerReferenceId
string or null

Updated partner reference ID.

Responses

Request samples

Content type
application/json
{
  • "status": "PENDING",
  • "partnerReferenceId": "string"
}

Response samples

Content type
application/json
{
  • "bookingId": "string",
  • "partnerReferenceId": "string",
  • "variantId": "string",
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "customersDetails": {
    },
  • "seatInfo": [
    ],
  • "price": {
    },
  • "status": "UNCAPTURED",
  • "voucherUrl": "string",
  • "tickets": [
    ],
  • "creationTimestamp": 0
}

Create a new booking (v2)

POST /bookings/

Overview

Create a new booking in UNCAPTURED state.

Booking creation follows a 2-step flow:

  1. Call this endpoint to create the booking — it returns the booking in UNCAPTURED state with a new bookingId.
  2. Call PUT /bookings/{bookingId}/ to capture the booking by setting the status to PENDING and assigning a partnerReferenceId. This starts fulfillment on the Headout side.

If the booking is not captured within 1 hour, the status automatically changes to CAPTURE_TIMEOUT.

Request

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Request Body

Field Type Required / Optional Description
productId String Required ID of the product.
variantId String Required ID of the variant to book.
inventoryId String Required ID of the inventory slot to book.
inventorySeatIds Array Optional List of seat IDs for seatmap-enabled products.
customersDetails Object Required Customer information (see below).
variantInputFields Array Optional Additional input fields specific to the variant.
price Object Required Expected price for the booking.
Request Example 
{
  "productId": "18969",
  "variantId": "25525",
  "inventoryId": "501183605",
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "NAME",
            "value": "John Doe"
          },
          {
            "id": "EMAIL",
            "value": "john@example.com"
          },
          {
            "id": "PHONE",
            "value": "+14155551234"
          }
        ]
      }
    ]
  },
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  }
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": null,
  "variantId": "25525",
  "status": "UNCAPTURED",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "NAME",
            "name": "Name",
            "value": "John Doe"
          },
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          },
          {
            "id": "PHONE",
            "name": "Phone",
            "value": "+14155551234"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": []
}

Notes

  • All bookings start in UNCAPTURED status and must be captured within 1 hour via PUT /bookings/{bookingId}/.
  • The price in the response may differ from the request if currency conversion occurs.
  • tickets array is empty for new bookings and populated after fulfillment.
  • seatInfo is only populated for seatmap-enabled bookings.
  • variantInputFields is only populated when the variant requires additional input fields.

GET /bookings/

Overview

Returns a paginated list of bookings for the authenticated partner account.

Request

API Parameters

Parameter Required / Optional Description Default Value
offset Optional Number of bookings to skip. Start at 0 for the first page. 0
limit Optional Number of bookings per page. Maximum value is 20. 20

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "items": [
    {
      "bookingId": "126890",
      "partnerReferenceId": "AX67873DDFSR",
      "variantId": "25525",
      "status": "PENDING",
      "startDateTime": "2025-04-12T19:30:00",
      "product": {
        "id": "18969",
        "name": "Bali Swing Experience",
        "variant": {
          "id": "25525",
          "name": "Standard Entry"
        }
      },
      "customersDetails": {
        "count": 1,
        "customers": [
          {
            "personType": "ADULT",
            "isPrimary": true,
            "inputFields": [
              {
                "id": "EMAIL",
                "name": "Email",
                "value": "john@example.com"
              }
            ]
          }
        ]
      },
      "seatInfo": null,
      "variantInputFields": [],
      "price": {
        "amount": 77.08,
        "currencyCode": "USD"
      },
      "creationTimestamp": 1712953295,
      "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
      "tickets": [
        {
          "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
          "url": null,
          "type": "QRCODE"
        }
      ]
    }
  ],
  "nextUrl": "/api/public/v2/bookings/?offset=20&limit=20",
  "prevUrl": null,
  "total": 100,
  "nextOffset": 20
}

Response Fields

Field Type Description
items Array of Object Bookings for the current page.
nextUrl String / null URL to fetch the next page. null if this is the last page.
prevUrl String / null URL to fetch the previous page. null if this is the first page.
total Integer Total number of bookings across all pages.
nextOffset Integer / null Offset value for the next request. null if this is the last page.

Error Responses

Status Condition
400 offset is negative
400 limit is zero or negative

Notes

  • Maximum page size is 20. Any limit value above 20 is capped to 20.
  • Use offset and limit to paginate through results.

GET /bookings/{bookingId}/

Overview

Retrieve details of a specific booking by its ID. The booking must belong to the authenticated partner account.

Request

Path Parameters

Parameter Required / Optional Description
bookingId Required The booking ID.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "25525",
  "status": "PENDING",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ]
}

Error Responses

Status Condition
400 bookingId is not a valid numeric ID
403 Booking does not belong to the authenticated partner

PUT /bookings/{bookingId}/

Overview

Capture a booking by setting the status to PENDING and assigning a partnerReferenceId. This is the second step of the 2-step booking flow. Once captured, the booking enters the fulfillment process on the Headout side.

Request

Path Parameters

Parameter Required / Optional Description
bookingId Required The booking ID.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Request Body

Field Type Required / Optional Description
status String Required Must be PENDING to capture the booking.
partnerReferenceId String Required Partner's own reference ID for tracking the booking.
Request Example 
{
  "status": "PENDING",
  "partnerReferenceId": "AX67873DDFSR"
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "25525",
  "status": "PENDING",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ]
}

Error Responses

Status Condition
400 bookingId is not a valid numeric ID
400 status is not PENDING
403 Booking does not belong to the authenticated partner

Notes

  • Only PENDING is accepted as the status value. Any other value returns a 400 error.
  • The booking must be in UNCAPTURED status to be captured.
  • If the booking is not captured within 1 hour of creation, it automatically moves to CAPTURE_TIMEOUT status.

Booking Status Lifecycle

Status Description
UNCAPTURED Booking created but not yet captured by the partner.
PENDING Booking captured and pending fulfillment.
COMPLETED Booking fulfilled — tickets and vouchers are available.
CANCELLED Booking was cancelled.
FAILED Booking failed during processing.
CAPTURE_TIMEOUT Booking was not captured within 1 hour of creation.
Authorizations:
apiKeyAuth
Request Body schema: application/json
required
productId
required
string

ID of the product.
variantId
required
string

ID of the variant to book.
inventoryId
required
string

ID of the inventory slot to book.
inventorySeatIds
Array of strings or null

List of seat IDs for seatmap-enabled products.

required
object

Customer information.
Array of objects or null

Additional input fields specific to the variant.
required
object

Expected price for the booking.

Responses

Request samples

Content type
application/json
{
  • "productId": "string",
  • "variantId": "string",
  • "inventoryId": "string",
  • "inventorySeatIds": [
    ],
  • "customersDetails": {
    },
  • "variantInputFields": [
    ],
  • "price": {
    }
}

Response samples

Content type
application/json
{
  • "bookingId": "string",
  • "partnerReferenceId": "string",
  • "variantId": "string",
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "customersDetails": {
    },
  • "seatInfo": [
    ],
  • "variantInputFields": [
    ],
  • "price": {
    },
  • "status": "UNCAPTURED",
  • "voucherUrl": "string",
  • "tickets": [
    ],
  • "creationTimestamp": 0
}

List all bookings (v2)

POST /bookings/

Overview

Create a new booking in UNCAPTURED state.

Booking creation follows a 2-step flow:

  1. Call this endpoint to create the booking — it returns the booking in UNCAPTURED state with a new bookingId.
  2. Call PUT /bookings/{bookingId}/ to capture the booking by setting the status to PENDING and assigning a partnerReferenceId. This starts fulfillment on the Headout side.

If the booking is not captured within 1 hour, the status automatically changes to CAPTURE_TIMEOUT.

Request

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Request Body

Field Type Required / Optional Description
productId String Required ID of the product.
variantId String Required ID of the variant to book.
inventoryId String Required ID of the inventory slot to book.
inventorySeatIds Array Optional List of seat IDs for seatmap-enabled products.
customersDetails Object Required Customer information (see below).
variantInputFields Array Optional Additional input fields specific to the variant.
price Object Required Expected price for the booking.
Request Example 
{
  "productId": "18969",
  "variantId": "25525",
  "inventoryId": "501183605",
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "NAME",
            "value": "John Doe"
          },
          {
            "id": "EMAIL",
            "value": "john@example.com"
          },
          {
            "id": "PHONE",
            "value": "+14155551234"
          }
        ]
      }
    ]
  },
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  }
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": null,
  "variantId": "25525",
  "status": "UNCAPTURED",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "NAME",
            "name": "Name",
            "value": "John Doe"
          },
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          },
          {
            "id": "PHONE",
            "name": "Phone",
            "value": "+14155551234"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": []
}

Notes

  • All bookings start in UNCAPTURED status and must be captured within 1 hour via PUT /bookings/{bookingId}/.
  • The price in the response may differ from the request if currency conversion occurs.
  • tickets array is empty for new bookings and populated after fulfillment.
  • seatInfo is only populated for seatmap-enabled bookings.
  • variantInputFields is only populated when the variant requires additional input fields.

GET /bookings/

Overview

Returns a paginated list of bookings for the authenticated partner account.

Request

API Parameters

Parameter Required / Optional Description Default Value
offset Optional Number of bookings to skip. Start at 0 for the first page. 0
limit Optional Number of bookings per page. Maximum value is 20. 20

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "items": [
    {
      "bookingId": "126890",
      "partnerReferenceId": "AX67873DDFSR",
      "variantId": "25525",
      "status": "PENDING",
      "startDateTime": "2025-04-12T19:30:00",
      "product": {
        "id": "18969",
        "name": "Bali Swing Experience",
        "variant": {
          "id": "25525",
          "name": "Standard Entry"
        }
      },
      "customersDetails": {
        "count": 1,
        "customers": [
          {
            "personType": "ADULT",
            "isPrimary": true,
            "inputFields": [
              {
                "id": "EMAIL",
                "name": "Email",
                "value": "john@example.com"
              }
            ]
          }
        ]
      },
      "seatInfo": null,
      "variantInputFields": [],
      "price": {
        "amount": 77.08,
        "currencyCode": "USD"
      },
      "creationTimestamp": 1712953295,
      "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
      "tickets": [
        {
          "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
          "url": null,
          "type": "QRCODE"
        }
      ]
    }
  ],
  "nextUrl": "/api/public/v2/bookings/?offset=20&limit=20",
  "prevUrl": null,
  "total": 100,
  "nextOffset": 20
}

Response Fields

Field Type Description
items Array of Object Bookings for the current page.
nextUrl String / null URL to fetch the next page. null if this is the last page.
prevUrl String / null URL to fetch the previous page. null if this is the first page.
total Integer Total number of bookings across all pages.
nextOffset Integer / null Offset value for the next request. null if this is the last page.

Error Responses

Status Condition
400 offset is negative
400 limit is zero or negative

Notes

  • Maximum page size is 20. Any limit value above 20 is capped to 20.
  • Use offset and limit to paginate through results.

GET /bookings/{bookingId}/

Overview

Retrieve details of a specific booking by its ID. The booking must belong to the authenticated partner account.

Request

Path Parameters

Parameter Required / Optional Description
bookingId Required The booking ID.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "25525",
  "status": "PENDING",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ]
}

Error Responses

Status Condition
400 bookingId is not a valid numeric ID
403 Booking does not belong to the authenticated partner

PUT /bookings/{bookingId}/

Overview

Capture a booking by setting the status to PENDING and assigning a partnerReferenceId. This is the second step of the 2-step booking flow. Once captured, the booking enters the fulfillment process on the Headout side.

Request

Path Parameters

Parameter Required / Optional Description
bookingId Required The booking ID.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Request Body

Field Type Required / Optional Description
status String Required Must be PENDING to capture the booking.
partnerReferenceId String Required Partner's own reference ID for tracking the booking.
Request Example 
{
  "status": "PENDING",
  "partnerReferenceId": "AX67873DDFSR"
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "25525",
  "status": "PENDING",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ]
}

Error Responses

Status Condition
400 bookingId is not a valid numeric ID
400 status is not PENDING
403 Booking does not belong to the authenticated partner

Notes

  • Only PENDING is accepted as the status value. Any other value returns a 400 error.
  • The booking must be in UNCAPTURED status to be captured.
  • If the booking is not captured within 1 hour of creation, it automatically moves to CAPTURE_TIMEOUT status.

Booking Status Lifecycle

Status Description
UNCAPTURED Booking created but not yet captured by the partner.
PENDING Booking captured and pending fulfillment.
COMPLETED Booking fulfilled — tickets and vouchers are available.
CANCELLED Booking was cancelled.
FAILED Booking failed during processing.
CAPTURE_TIMEOUT Booking was not captured within 1 hour of creation.
Authorizations:
apiKeyAuth
query Parameters
offset
integer
Default: 0

Number of bookings to skip.
limit
integer <= 20
Default: 20

Number of bookings per page. Maximum 20.

Responses

Request samples 

curl -X GET \
  "https://<host>/api/public/v2/bookings/?offset=0&limit=20" \
  -H "Headout-Auth: <API_KEY>"

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

Get a booking by ID (v2)

POST /bookings/

Overview

Create a new booking in UNCAPTURED state.

Booking creation follows a 2-step flow:

  1. Call this endpoint to create the booking — it returns the booking in UNCAPTURED state with a new bookingId.
  2. Call PUT /bookings/{bookingId}/ to capture the booking by setting the status to PENDING and assigning a partnerReferenceId. This starts fulfillment on the Headout side.

If the booking is not captured within 1 hour, the status automatically changes to CAPTURE_TIMEOUT.

Request

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Request Body

Field Type Required / Optional Description
productId String Required ID of the product.
variantId String Required ID of the variant to book.
inventoryId String Required ID of the inventory slot to book.
inventorySeatIds Array Optional List of seat IDs for seatmap-enabled products.
customersDetails Object Required Customer information (see below).
variantInputFields Array Optional Additional input fields specific to the variant.
price Object Required Expected price for the booking.
Request Example 
{
  "productId": "18969",
  "variantId": "25525",
  "inventoryId": "501183605",
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "NAME",
            "value": "John Doe"
          },
          {
            "id": "EMAIL",
            "value": "john@example.com"
          },
          {
            "id": "PHONE",
            "value": "+14155551234"
          }
        ]
      }
    ]
  },
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  }
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": null,
  "variantId": "25525",
  "status": "UNCAPTURED",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "NAME",
            "name": "Name",
            "value": "John Doe"
          },
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          },
          {
            "id": "PHONE",
            "name": "Phone",
            "value": "+14155551234"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": []
}

Notes

  • All bookings start in UNCAPTURED status and must be captured within 1 hour via PUT /bookings/{bookingId}/.
  • The price in the response may differ from the request if currency conversion occurs.
  • tickets array is empty for new bookings and populated after fulfillment.
  • seatInfo is only populated for seatmap-enabled bookings.
  • variantInputFields is only populated when the variant requires additional input fields.

GET /bookings/

Overview

Returns a paginated list of bookings for the authenticated partner account.

Request

API Parameters

Parameter Required / Optional Description Default Value
offset Optional Number of bookings to skip. Start at 0 for the first page. 0
limit Optional Number of bookings per page. Maximum value is 20. 20

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "items": [
    {
      "bookingId": "126890",
      "partnerReferenceId": "AX67873DDFSR",
      "variantId": "25525",
      "status": "PENDING",
      "startDateTime": "2025-04-12T19:30:00",
      "product": {
        "id": "18969",
        "name": "Bali Swing Experience",
        "variant": {
          "id": "25525",
          "name": "Standard Entry"
        }
      },
      "customersDetails": {
        "count": 1,
        "customers": [
          {
            "personType": "ADULT",
            "isPrimary": true,
            "inputFields": [
              {
                "id": "EMAIL",
                "name": "Email",
                "value": "john@example.com"
              }
            ]
          }
        ]
      },
      "seatInfo": null,
      "variantInputFields": [],
      "price": {
        "amount": 77.08,
        "currencyCode": "USD"
      },
      "creationTimestamp": 1712953295,
      "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
      "tickets": [
        {
          "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
          "url": null,
          "type": "QRCODE"
        }
      ]
    }
  ],
  "nextUrl": "/api/public/v2/bookings/?offset=20&limit=20",
  "prevUrl": null,
  "total": 100,
  "nextOffset": 20
}

Response Fields

Field Type Description
items Array of Object Bookings for the current page.
nextUrl String / null URL to fetch the next page. null if this is the last page.
prevUrl String / null URL to fetch the previous page. null if this is the first page.
total Integer Total number of bookings across all pages.
nextOffset Integer / null Offset value for the next request. null if this is the last page.

Error Responses

Status Condition
400 offset is negative
400 limit is zero or negative

Notes

  • Maximum page size is 20. Any limit value above 20 is capped to 20.
  • Use offset and limit to paginate through results.

GET /bookings/{bookingId}/

Overview

Retrieve details of a specific booking by its ID. The booking must belong to the authenticated partner account.

Request

Path Parameters

Parameter Required / Optional Description
bookingId Required The booking ID.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "25525",
  "status": "PENDING",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ]
}

Error Responses

Status Condition
400 bookingId is not a valid numeric ID
403 Booking does not belong to the authenticated partner

PUT /bookings/{bookingId}/

Overview

Capture a booking by setting the status to PENDING and assigning a partnerReferenceId. This is the second step of the 2-step booking flow. Once captured, the booking enters the fulfillment process on the Headout side.

Request

Path Parameters

Parameter Required / Optional Description
bookingId Required The booking ID.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Request Body

Field Type Required / Optional Description
status String Required Must be PENDING to capture the booking.
partnerReferenceId String Required Partner's own reference ID for tracking the booking.
Request Example 
{
  "status": "PENDING",
  "partnerReferenceId": "AX67873DDFSR"
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "25525",
  "status": "PENDING",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ]
}

Error Responses

Status Condition
400 bookingId is not a valid numeric ID
400 status is not PENDING
403 Booking does not belong to the authenticated partner

Notes

  • Only PENDING is accepted as the status value. Any other value returns a 400 error.
  • The booking must be in UNCAPTURED status to be captured.
  • If the booking is not captured within 1 hour of creation, it automatically moves to CAPTURE_TIMEOUT status.

Booking Status Lifecycle

Status Description
UNCAPTURED Booking created but not yet captured by the partner.
PENDING Booking captured and pending fulfillment.
COMPLETED Booking fulfilled — tickets and vouchers are available.
CANCELLED Booking was cancelled.
FAILED Booking failed during processing.
CAPTURE_TIMEOUT Booking was not captured within 1 hour of creation.
Authorizations:
apiKeyAuth
path Parameters
bookingId
required
string

The booking ID.

Responses

Request samples 

curl -X GET \
  "https://<host>/api/public/v2/bookings/126890/" \
  -H "Headout-Auth: <API_KEY>"

Response samples

Content type
application/json
{
  • "bookingId": "string",
  • "partnerReferenceId": "string",
  • "variantId": "string",
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "customersDetails": {
    },
  • "seatInfo": [
    ],
  • "variantInputFields": [
    ],
  • "price": {
    },
  • "status": "UNCAPTURED",
  • "voucherUrl": "string",
  • "tickets": [
    ],
  • "creationTimestamp": 0
}

Capture a booking (v2)

POST /bookings/

Overview

Create a new booking in UNCAPTURED state.

Booking creation follows a 2-step flow:

  1. Call this endpoint to create the booking — it returns the booking in UNCAPTURED state with a new bookingId.
  2. Call PUT /bookings/{bookingId}/ to capture the booking by setting the status to PENDING and assigning a partnerReferenceId. This starts fulfillment on the Headout side.

If the booking is not captured within 1 hour, the status automatically changes to CAPTURE_TIMEOUT.

Request

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Request Body

Field Type Required / Optional Description
productId String Required ID of the product.
variantId String Required ID of the variant to book.
inventoryId String Required ID of the inventory slot to book.
inventorySeatIds Array Optional List of seat IDs for seatmap-enabled products.
customersDetails Object Required Customer information (see below).
variantInputFields Array Optional Additional input fields specific to the variant.
price Object Required Expected price for the booking.
Request Example 
{
  "productId": "18969",
  "variantId": "25525",
  "inventoryId": "501183605",
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "NAME",
            "value": "John Doe"
          },
          {
            "id": "EMAIL",
            "value": "john@example.com"
          },
          {
            "id": "PHONE",
            "value": "+14155551234"
          }
        ]
      }
    ]
  },
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  }
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": null,
  "variantId": "25525",
  "status": "UNCAPTURED",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "NAME",
            "name": "Name",
            "value": "John Doe"
          },
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          },
          {
            "id": "PHONE",
            "name": "Phone",
            "value": "+14155551234"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": []
}

Notes

  • All bookings start in UNCAPTURED status and must be captured within 1 hour via PUT /bookings/{bookingId}/.
  • The price in the response may differ from the request if currency conversion occurs.
  • tickets array is empty for new bookings and populated after fulfillment.
  • seatInfo is only populated for seatmap-enabled bookings.
  • variantInputFields is only populated when the variant requires additional input fields.

GET /bookings/

Overview

Returns a paginated list of bookings for the authenticated partner account.

Request

API Parameters

Parameter Required / Optional Description Default Value
offset Optional Number of bookings to skip. Start at 0 for the first page. 0
limit Optional Number of bookings per page. Maximum value is 20. 20

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "items": [
    {
      "bookingId": "126890",
      "partnerReferenceId": "AX67873DDFSR",
      "variantId": "25525",
      "status": "PENDING",
      "startDateTime": "2025-04-12T19:30:00",
      "product": {
        "id": "18969",
        "name": "Bali Swing Experience",
        "variant": {
          "id": "25525",
          "name": "Standard Entry"
        }
      },
      "customersDetails": {
        "count": 1,
        "customers": [
          {
            "personType": "ADULT",
            "isPrimary": true,
            "inputFields": [
              {
                "id": "EMAIL",
                "name": "Email",
                "value": "john@example.com"
              }
            ]
          }
        ]
      },
      "seatInfo": null,
      "variantInputFields": [],
      "price": {
        "amount": 77.08,
        "currencyCode": "USD"
      },
      "creationTimestamp": 1712953295,
      "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
      "tickets": [
        {
          "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
          "url": null,
          "type": "QRCODE"
        }
      ]
    }
  ],
  "nextUrl": "/api/public/v2/bookings/?offset=20&limit=20",
  "prevUrl": null,
  "total": 100,
  "nextOffset": 20
}

Response Fields

Field Type Description
items Array of Object Bookings for the current page.
nextUrl String / null URL to fetch the next page. null if this is the last page.
prevUrl String / null URL to fetch the previous page. null if this is the first page.
total Integer Total number of bookings across all pages.
nextOffset Integer / null Offset value for the next request. null if this is the last page.

Error Responses

Status Condition
400 offset is negative
400 limit is zero or negative

Notes

  • Maximum page size is 20. Any limit value above 20 is capped to 20.
  • Use offset and limit to paginate through results.

GET /bookings/{bookingId}/

Overview

Retrieve details of a specific booking by its ID. The booking must belong to the authenticated partner account.

Request

Path Parameters

Parameter Required / Optional Description
bookingId Required The booking ID.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "25525",
  "status": "PENDING",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ]
}

Error Responses

Status Condition
400 bookingId is not a valid numeric ID
403 Booking does not belong to the authenticated partner

PUT /bookings/{bookingId}/

Overview

Capture a booking by setting the status to PENDING and assigning a partnerReferenceId. This is the second step of the 2-step booking flow. Once captured, the booking enters the fulfillment process on the Headout side.

Request

Path Parameters

Parameter Required / Optional Description
bookingId Required The booking ID.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Request Body

Field Type Required / Optional Description
status String Required Must be PENDING to capture the booking.
partnerReferenceId String Required Partner's own reference ID for tracking the booking.
Request Example 
{
  "status": "PENDING",
  "partnerReferenceId": "AX67873DDFSR"
}

Response

Response Example 
{
  "bookingId": "126890",
  "partnerReferenceId": "AX67873DDFSR",
  "variantId": "25525",
  "status": "PENDING",
  "startDateTime": "2025-04-12T19:30:00",
  "product": {
    "id": "18969",
    "name": "Bali Swing Experience",
    "variant": {
      "id": "25525",
      "name": "Standard Entry"
    }
  },
  "customersDetails": {
    "count": 1,
    "customers": [
      {
        "personType": "ADULT",
        "isPrimary": true,
        "inputFields": [
          {
            "id": "EMAIL",
            "name": "Email",
            "value": "john@example.com"
          }
        ]
      }
    ]
  },
  "seatInfo": null,
  "variantInputFields": [],
  "price": {
    "amount": 77.08,
    "currencyCode": "USD"
  },
  "creationTimestamp": 1712953295,
  "voucherUrl": "https://www.headout.com/voucher/126890?key=...",
  "tickets": [
    {
      "publicId": "9e4d8330-abc7-40f8-951d-19b9e8731dcf",
      "url": null,
      "type": "QRCODE"
    }
  ]
}

Error Responses

Status Condition
400 bookingId is not a valid numeric ID
400 status is not PENDING
403 Booking does not belong to the authenticated partner

Notes

  • Only PENDING is accepted as the status value. Any other value returns a 400 error.
  • The booking must be in UNCAPTURED status to be captured.
  • If the booking is not captured within 1 hour of creation, it automatically moves to CAPTURE_TIMEOUT status.

Booking Status Lifecycle

Status Description
UNCAPTURED Booking created but not yet captured by the partner.
PENDING Booking captured and pending fulfillment.
COMPLETED Booking fulfilled — tickets and vouchers are available.
CANCELLED Booking was cancelled.
FAILED Booking failed during processing.
CAPTURE_TIMEOUT Booking was not captured within 1 hour of creation.
Authorizations:
apiKeyAuth
path Parameters
bookingId
required
string

The booking ID.
Request Body schema: application/json
required
status
string
Enum: "PENDING" "UNCAPTURED" "COMPLETED" "CANCELLED" "FAILED"

Updated status of the booking.
partnerReferenceId
string or null

Updated partner reference ID.

Responses

Request samples

Content type
application/json
{
  • "status": "PENDING",
  • "partnerReferenceId": "string"
}

Response samples

Content type
application/json
{
  • "bookingId": "string",
  • "partnerReferenceId": "string",
  • "variantId": "string",
  • "startDateTime": "2019-08-24T14:15:22Z",
  • "product": {
    },
  • "customersDetails": {
    },
  • "seatInfo": [
    ],
  • "variantInputFields": [
    ],
  • "price": {
    },
  • "status": "UNCAPTURED",
  • "voucherUrl": "string",
  • "tickets": [
    ],
  • "creationTimestamp": 0
}

Cancel a booking

Submit a cancellation request for a bookingId owned by your partner account. This validates input and ownership, creates a request log with status SUBMITTED, and enqueues an asynchronous job for downstream processing. The immediate response acknowledges submission and does not represent the final booking outcome.

Base path: /api/public/v2/bookings

Authorizations:
apiKeyAuth
path Parameters
bookingId
required
string

Booking identifier owned by the calling partner.
Request Body schema: application/json
required
reason
required
string
Enum: "TICKETS_NOT_RECEIVED" "CHANGE_OF_TRAVEL_PLANS" "MODIFY_EXISTING_RESERVATION" "FOUND_CHEAPER_OPTION_ELSEWHERE" "OTHER"

Cancellation reason.
comment
string or null

Optional free-text comment

Responses

Request samples

Content type
application/json
{
  • "reason": "CHANGE_OF_TRAVEL_PLANS",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Cancellation request submitted successfully"
}

Reschedule a booking

Submit a reschedule request for a bookingId owned by your partner account. This validates input and ownership, creates a request log with status SUBMITTED, and enqueues an asynchronous job for downstream processing. The immediate response acknowledges submission and does not represent the final booking outcome.

Base path: /api/public/v2/bookings

Authorizations:
apiKeyAuth
path Parameters
bookingId
required
string

Booking identifier owned by the calling partner.
Request Body schema: application/json
required
startDateTime
required
string <date-time>

Local date-time values.
endDateTime
required
string <date-time>

Local date-time values.
comment
string or null

Optional free-text comment

Responses

Request samples

Content type
application/json
{
  • "startDateTime": "2025-11-02T09:00:00",
  • "endDateTime": "2025-11-02T11:00:00",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Cancellation request submitted successfully"
}

Cancel a booking (Deprecated) Deprecated

⚠️ Deprecated — This endpoint will be removed in a future release. Use POST /api/public/v2/bookings/{bookingId}/cancel/ instead.

Submit a cancellation request for a bookingId owned by your partner account. This validates input and ownership, creates a request log with status SUBMITTED, and enqueues an asynchronous job for downstream processing. The immediate response acknowledges submission and does not represent the final booking outcome.

Base path: /api/public/v2/partner/booking

Authorizations:
apiKeyAuth
path Parameters
bookingId
required
string

Booking identifier owned by the calling partner.
Request Body schema: application/json
required
reason
required
string
Enum: "TICKETS_NOT_RECEIVED" "CHANGE_OF_TRAVEL_PLANS" "MODIFY_EXISTING_RESERVATION" "FOUND_CHEAPER_OPTION_ELSEWHERE" "OTHER"

Cancellation reason.
comment
string or null

Optional free-text comment

Responses

Request samples

Content type
application/json
{
  • "reason": "CHANGE_OF_TRAVEL_PLANS",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Cancellation request submitted successfully"
}

Reschedule a booking (Deprecated) Deprecated

⚠️ Deprecated — This endpoint will be removed in a future release. Use POST /api/public/v2/bookings/{bookingId}/reschedule/ instead.

Submit a reschedule request for a bookingId owned by your partner account. This validates input and ownership, creates a request log with status SUBMITTED, and enqueues an asynchronous job for downstream processing. The immediate response acknowledges submission and does not represent the final booking outcome.

Base path: /api/public/v2/partner/booking

Authorizations:
apiKeyAuth
path Parameters
bookingId
required
string

Booking identifier owned by the calling partner.
Request Body schema: application/json
required
startDateTime
required
string <date-time>

Local date-time values.
endDateTime
required
string <date-time>

Local date-time values.
comment
string or null

Optional free-text comment

Responses

Request samples

Content type
application/json
{
  • "startDateTime": "2025-11-02T09:00:00",
  • "endDateTime": "2025-11-02T11:00:00",
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Cancellation request submitted successfully"
}

Collection

Collection operations

List all categories by city

GET /category/list-by/city

Retrieve a list of all categories for a specific city.

Request

MODE KEY TYPE OPTIONAL DESCRIPTION
QUERY cityCode string no The city code. Eg: NEW_YORK, DUBAI
QUERY offset string yes The offset for pagination. Ref: Pagination - Request Params
QUERY limit int yes The limit for pagination. Ref: Pagination - Request Params

Response

Response Example 
{
    "items": [
        {
            "id": "123",
            "name": "Broadway",
            "cityCode": "NEW_YORK",
            "canonicalUrl": "https://www.headout.com/category/24/broadway"
        }
    ],
    "nextUrl": "https://www.headout.com/api/public/v1/category/list-by/city?cityCode=NEW_YORK,offset=21,limit=20",
    "prevUrl": "https://www.headout.com/api/public/v1/category/list-by/city?cityCode=NEW_YORK,offset=0,limit=20",
    "total": 100,
    "nextOffset": 21
}
Authorizations:
apiKeyAuth
query Parameters
cityCode
required
string

City code to list categories for.
offset
string

Number of items to skip before starting to collect the result set.
limit
integer

Maximum number of items to return.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v1/category/list-by/city?cityCode=DUBAI' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

List all collections

GET /collections

Overview

The Partner Collections API v2 provides endpoints for accessing the collections. This API is designed to facilitate partners in fetching relevant data for different cities and languages.

Request

API Parameters

Parameter Required / Optional Description Default Value
cityCode Required The city code to fetch collections for.
languageCode Optional Language code. EN
offset Optional Offset for pagination. 0
limit Optional Limit for pagination. 10

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "collections": [
    {
      "id": "24",
      "name": "Broadway",
      "cityCode": "NEW_YORK",
      "localeSpecificUrls": {
        "EN": "/broadway-tickets-c-24/",
        "ES": "/es/entradas-espectaculos-de-broadway-c-24/",
        "FR": "/fr/billets-comedie-musicale-broadway-c-24/",
        "IT": "/it/broadway-biglietti-c-24/",
        "DE": "/de/broadway-tickets-c-24/",
        "PT": "/pt/broadway-c-24/",
        "NL": "/nl/broadway-c-24/"
      },
      "canonicalUrl": "https://www.headout.com/broadway-tickets-c-24/"
    },
    {
      "id": "161",
      "name": "Off Broadway Show Tickets",
      "cityCode": "NEW_YORK",
      "localeSpecificUrls": {
        "EN": "/off-broadway-show-tickets-c-161/",
        "ES": "/es/entradas-espectaculos-off-broadway-c-161/",
        "FR": "/fr/off-broadway-c-161/",
        "IT": "/it/biglietti-per-spettacoli-off-broadway-c-161/",
        "DE": "/de/off-broadway-c-161/",
        "PT": "/pt/ingressos-para-espetaculos-off-broadway-c-161/",
        "NL": "/nl/off-broadway-c-161/"
      },
      "canonicalUrl": "https://www.headout.com/off-broadway-show-tickets-c-161/"
    },
    {
      "id": "121",
      "name": "Statue of Liberty",
      "cityCode": "NEW_YORK",
      "localeSpecificUrls": {
        "EN": "/statue-of-liberty-cruises-c-121/",
        "ES": "/es/estatua-de-la-libertad-c-121/",
        "FR": "/fr/statue-de-la-liberte-c-121/",
        "IT": "/it/statua-della-liberta-c-121/",
        "DE": "/de/freiheitsstatue-c-121/",
        "PT": "/pt/estatua-da-liberdade-c-121/",
        "NL": "/nl/vrijheidsbeeld-c-121/"
      },
      "canonicalUrl": "https://www.headout.com/statue-of-liberty-cruises-c-121/"
    }
  ],
  "nextUrl": null,
  "prevUrl": null,
  "total": 3,
  "nextOffset": null
}

Notes

  • Ensure that all required parameters are included in your requests.
  • Use appropriate city and language codes as per your application requirements.
  • Pagination parameters (offset and limit) help in managing large datasets.
Authorizations:
apiKeyAuth
query Parameters
cityCode
required
string

The code of the city for which data is being requested.
languageCode
string
Default: "EN"
Enum: "EN" "ES" "FR" "IT" "DE" "PT" "NL" "PL"

The language code for localization. Default is 'EN'.
offset
string

The number of items to skip before starting to collect the result set.
limit
integer

The numbers of items to return.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v2/collections?cityCode=<CITY_CODE>&languageCode=<LANGUAGE_CODE>&limit=<LIMIT>&offset=<OFFSET>' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "collections": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

City

City operations

List all active cities (legacy)

GET /city

List all the active cities.

Request

MODE KEY TYPE OPTIONAL DESCRIPTION
QUERY offset string yes The offset for pagination. Ref: Pagination - Request Params
QUERY limit int yes The limit for pagination. Ref: Pagination - Request Params

Response

Response Example 
{
    "items": [
        {
            "code": "NEW_YORK",
            "name": "New York",
            "image": "https://cdn-imgix.headout.com/cities/new-york/images/mobile/morning.jpg"
        }
    ],
    "nextUrl": "https://www.headout.com/api/public/v1/city?offset=21,limit=20",
    "prevUrl": "https://www.headout.com/api/public/v1/city?offset=0,limit=20",
    "total": 100,
    "nextOffset": 21
}
Authorizations:
apiKeyAuth
query Parameters
offset
string

Number of items to skip before starting to collect the result set.
limit
integer

Maximum number of items to return.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v1/city' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

List all cities

GET /cities/

Overview

Returns a paginated list of all cities available on Headout, sorted alphabetically by name. Each city includes a code, a display name, and an image. Use the city code as the cityCode parameter in other v2 endpoints. Page size is fixed at 20.

Request

API Parameters

Parameter Required / Optional Description Default Value
offset Optional Number of cities to skip. Start at 0 for the first page. Increment by 20 to fetch subsequent pages. 0

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "cities": [
    {
      "code": "AMSTERDAM",
      "name": "Amsterdam",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/amsterdam-city.jpeg"
      }
    },
    {
      "code": "BARCELONA",
      "name": "Barcelona",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/barcelona-city.jpeg"
      }
    },
    {
      "code": "BERLIN",
      "name": "Berlin",
      "image": {
        "url": "//cdn-imgix.headout.com/media/images/berlin-city.jpeg"
      }
    }
  ],
  "nextUrl": "/api/public/v2/cities/?offset=20",
  "prevUrl": null,
  "total": 142,
  "nextOffset": 20
}

Response Fields

Field Type Description
cities Array of Object Cities for the current page, sorted alphabetically by name.
nextUrl String / null URL to fetch the next page. null if this is the last page.
prevUrl String / null URL to fetch the previous page. null if this is the first page.
total Integer Total number of cities across all pages.
nextOffset Integer / null Offset value for the next request. null if this is the last page.

City Object

Field Type Description
code String City code (e.g., NEW_YORK, DUBAI). Pass this as the cityCode parameter in other endpoints.
name String Display name of the city (e.g., "New York", "Dubai").
image Object City image that can be used in your UI. Contains a url field with the CDN URL.

Error Responses

Status Condition
400 offset is negative

Notes

  • Cities are sorted alphabetically by name.
  • Page size is fixed at 20. There is no limit parameter — use offset to paginate.
  • Use the code field from this response as the cityCode parameter in other v2 endpoints (products, categories, collections, etc.).
Authorizations:
apiKeyAuth
query Parameters
offset
integer >= 0
Default: 0

Number of cities to skip. Start at 0 for the first page. Increment by 20 to fetch subsequent pages.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v2/cities/' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "cities": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

Variant

Variant operations

List available inventory for a variant

GET /inventory/list-by/variant

Get the available inventory for a variant.

Request

MODE KEY TYPE OPTIONAL DESCRIPTION
QUERY variantId string no The ID of the variant for which the inventory needs to be fetched.
QUERY startDateTime string yes The start date time from which the inventory needs to be fetched. If unspecified then the current timestamp is taken into consideration. Format: fm-date-time. Ref: inventory.startDateTime
QUERY endDateTime string yes The end date time till which the inventory needs to be fetched. If unspecified then this is taken as infinity. Format: fm-date-time. Ref: inventory.startDateTime
QUERY offset string yes The offset for pagination. Ref: Pagination - Request Params
QUERY limit int yes The limit for pagination. Ref: Pagination - Request Params
QUERY currencyCode string yes The currency in which pricing information will be returned. Eg: USD, AED. Ref: https://en.wikipedia.org/wiki/ISO_4217

Response

Response Example 
{
    "items": [
        {
            "id": "1212121",
            "startDateTime": "2017-03-30T15:30:00",
            "endDateTime": "2017-03-30T15:30:00",
            "availability": "LIMITED/UNLIMITED/CLOSED",
            "remaining": 5,
            "pricing": {
                "persons": [
                    {
                        "type": "ADULT",
                        "name": "Adult",
                        "ageFrom": 13,
                        "ageTo": null,
                        "price": 100,
                        "originalPrice": 110
                    },
                    {
                        "type": "CHILD",
                        "name": "Child",
                        "ageFrom": 4,
                        "ageTo": 12,
                        "price": 50,
                        "originalPrice": 60
                    }
                ],
                "groups": [
                    {
                        "size": 4,
                        "price": 100,
                        "originalPrice": 120
                    }
                ]
            }
        }
    ],
    "nextUrl": "https://www.headout.com/api/public/v1/inventory/list-by/variant?variantId=1234&offset=21&limit=20",
    "prevUrl": "https://www.headout.com/api/public/v1/inventory/list-by/variant?variantId=1234&offset=0&limit=20",
    "total": 100,
    "nextOffset": 21
}
Authorizations:
apiKeyAuth
query Parameters
variantId
required
string

ID of the variant to list inventory for.
startDateTime
string

Start date and time for inventory availability.
endDateTime
string

End date and time for inventory availability.

offset
string

Number of items to skip before starting to collect the result set.
limit
integer

Maximum number of items to return.
currencyCode
string
Enum: "EUR" "GBP" "AED" "USD" "SGD" "AUD" "THB" "INR" "HKD" "KRW" "CAD" "JPY" "NZD" "CHF" "ZAR" "MYR" "BRL" "RUB" "SEK" "IDR" "ISK" "MOP" "CNY" "TWD" "MXN" "EGP" "QAR" "SAR" "DKK" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BSD" "BTN" "BWP" "BYR" "BZD" "CDF" "CLP" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DOP" "DZD" "ERN" "ETB" "FJD" "FKP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HNL" "HRK" "HTG" "HUF" "ILS" "IMP" "IQD" "IRR" "JEP" "JMD" "JOD" "KES" "KGS" "KHR" "KMF" "KPW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MRO" "MUR" "MVR" "MWK" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "RON" "RSD" "RWF" "SBD" "SCR" "SDG" "SHP" "SLL" "SOS" "SPL" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TZS" "UAH" "UGX" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XCD" "XDR" "XOF" "XPF" "YER" "ZMW" "ZWD"

Currency code for inventory pricing.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v1/inventory/list-by/variant?variantId=2671&offset=0&limit=150&currencyCode=AED' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

Product

Product operations

Get product by ID

GET /product/get/{product_id}

Gets a product by productId.

Request

MODE KEY TYPE OPTIONAL DESCRIPTION
PATH productId string no Product id
QUERY currencyCode string yes The currency in which pricing information will be returned. Eg: USD, AED. Ref: https://en.wikipedia.org/wiki/ISO_4217
QUERY fetch-variants boolean yes (Default: true) Flag to toggle the option of fetching variants.
QUERY language string yes (Default: EN) The language in which the product details will be returned. Eg: EN, ES, FR, IT, DE, PT, NL, etc.

Response

Response Example 
{
  "id": 512,
  "name": "Wicked",
  "url": "/broadway-tickets/wicked-e-512/",
  "canonicalUrl": "https://www.headout.com/broadway-tickets/wicked-e-512/",
  "neighbourhood": "",
  "city": {
    "name": "New York",
    "code": "NEW_YORK"
  },
  "currency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "US$",
    "localSymbol": "$",
    "precision": 2
  },
  "displayTags": [
    "Broadway",
    "Musical",
    "Best of Broadway",
    "Entertainment"
  ],
  "images": [
    {
      "url": "https://cdn-imgix.headout.com/media/images/5276fb91a066165e4069516143ae2ea3-512-new-york-wicked-01.jpg",
      "altText": "wicked-1",
      "description": "Wicked Newyork",
      "credit": "Broadway Inbound, Inc"
    }
  ],
  "contentListHtml": [
    {
      "title": "Summary",
      "type": "SUMMARY_HTML",
      "html": "<h2>Why Watch Wicked</h2>\n<p>Dive deep into the enchanting world of Oz, presented from a perspective you've never witnessed before. Secure your Wicked Broadway tickets to step into a multi-award-winning phenomenon. With its spellbinding cast, extraordinary crew, and accolades that stretch beyond Broadway's glimmering lights, Wicked is an unmatched theatrical experience. The numerous awards and consistent critical acclaim stand testimony to its brilliance. Don't miss your chance to be swept away by this bewitching tale of friendship, love, and the cost of integrity.</p>\n<h2>The Story</h2>\n<p>Before Dorothy and her famous ruby slippers, there was a profound friendship between two young women, one with emerald green skin. This is their story. Book your Wicked Broadway tickets now and embark on a magical journey that unveils the untold tale of the witches of Oz. Witness the transformation of Elphaba, the future Wicked Witch of the West, and Glinda, the Good Witch. It's a mesmerizing, heart-tugging story filled with songs and emotions that promise to leave an indelible mark on your soul.</p>\n<h2>Great For</h2>\n<p>Fans of Fantasy | Musical Enthusiasts | Night Out with Family</p>"
    }
  ],
  "content": [
    {
      "title": "Summary",
      "type": "SUMMARY_HTML",
      "html": "<h2>Why Watch Wicked</h2>\n<p>Dive deep into the enchanting world of Oz, presented from a perspective you've never witnessed before. Secure your Wicked Broadway tickets to step into a multi-award-winning phenomenon. With its spellbinding cast, extraordinary crew, and accolades that stretch beyond Broadway's glimmering lights, Wicked is an unmatched theatrical experience. The numerous awards and consistent critical acclaim stand testimony to its brilliance. Don't miss your chance to be swept away by this bewitching tale of friendship, love, and the cost of integrity.</p>\n<h2>The Story</h2>\n<p>Before Dorothy and her famous ruby slippers, there was a profound friendship between two young women, one with emerald green skin. This is their story. Book your Wicked Broadway tickets now and embark on a magical journey that unveils the untold tale of the witches of Oz. Witness the transformation of Elphaba, the future Wicked Witch of the West, and Glinda, the Good Witch. It's a mesmerizing, heart-tugging story filled with songs and emotions that promise to leave an indelible mark on your soul.</p>\n<h2>Great For</h2>\n<p>Fans of Fantasy | Musical Enthusiasts | Night Out with Family</p>"
    }
  ],
  "startLocation": {
    "geolocation": {
      "latitude": 40.762332916259766,
      "longitude": -73.98523712158203
    },
    "address": {
      "addressLine1": "Gershwin Theatre",
      "addressLine2": "222 West 51 Street",
      "cityName": "New York",
      "postalCode": "10019",
      "state": "New York",
      "countryName": "United States"
    }
  },
  "endLocation": {
    "geolocation": {
      "latitude": 40.762332916259766,
      "longitude": -73.98523712158203
    },
    "address": {
      "addressLine1": "Gershwin Theatre",
      "addressLine2": "222 West 51 Street",
      "cityName": "New York",
      "postalCode": "10019",
      "state": "New York",
      "countryName": "United States"
    }
  },
  "productType": "EVENT",
  "ratingCumulative": {
    "avg": 4.43,
    "count": 1262
  },
  "hasInstantConfirmation": false,
  "hasMobileTicket": false,
  "variants": [
    {
      "id": 647,
      "name": "Rear Orchestra/Rear Mezzanine",
      "description": "",
      "duration": 9900000,
      "inventoryType": "FIXED_START_FIXED_DURATION",
      "pax": {
        "min": 1,
        "max": 8
      },
      "cashback": {
        "value": 0.0000,
        "type": "PERCENTAGE"
      },
      "ticketDeliveryInfoHtml": null,
      "inputFields": [
        {
          "oldId": 62,
          "id": "NAME",
          "name": "Full Name",
          "dataType": "STRING",
          "validation": {
            "regex": "\\s*[^\\s]+\\s+[^\\s]+.*",
            "minLength": 3,
            "maxLength": 80,
            "minValue": null,
            "maxValue": null,
            "required": true,
            "values": null
          },
          "level": "PRIMARY_CUSTOMER"
        },
        {
          "oldId": 237880,
          "id": "CUSTOM_237880",
          "name": "Passport Details",
          "description": "Passport ID number",
          "dataType": "STRING",
          "validation": {
            "regex": null,
            "minLength": null,
            "maxLength": null,
            "minValue": null,
            "maxValue": null,
            "required": true,
            "values": null
          },
          "level": "ALL_CUSTOMER"
        },
        {
          "oldId": 247089,
          "id": "CUSTOM_247089",
          "name": "Pickup Location",
          "description": "Please select your pickup location",
          "dataType": "LOCATION",
          "validation": {
            "regex": null,
            "minLength": null,
            "maxLength": null,
            "minValue": null,
            "maxValue": null,
            "required": true,
            "values": [
              {
                "id": 292744,
                "latitude": 7.79685,
                "longitude": 98.311755,
                "address": "Rawai, Mueang Phuket District, Phuket 83100, Thailand",
                "displayName": "2c Phuket Residence",
                "timingConfig": {
                  "startTime": null,
                  "endTime": null,
                  "minPeriod": null,
                  "maxPeriod": null
                },
                "note": null
              },
              {
                "id": 292745,
                "latitude": 7.880448,
                "longitude": 98.39225,
                "address": "Phuket, Mueang Phuket District, Phuket 83000, Thailand",
                "displayName": "A2 Home",
                "timingConfig": {
                  "startTime": null,
                  "endTime": null,
                  "minPeriod": null,
                  "maxPeriod": null
                },
                "note": null
              }
            ]
          },
          "level": "PRIMARY_CUSTOMER"
        },
      ],
      "tags": [
        "BROADWAY",
        "BROADWAY2",
        "BROADWAYFORKIDS",
        "BROADWAYFORKIDS2",
        "BTTFA"
      ]
    }
  ],
  "pricing": {
    "type": "PER_PERSON",
    "currencyCode": "USD",
    "minimumPrice": {
      "originalPrice": 96.50,
      "finalPrice": 96.50
    },
    "bestDiscount": 0
  }
}
Authorizations:
apiKeyAuth
path Parameters
productId
required
string

ID of the product to fetch.
query Parameters
currencyCode
string
Enum: "EUR" "GBP" "AED" "USD" "SGD" "AUD" "THB" "INR" "HKD" "KRW" "CAD" "JPY" "NZD" "CHF" "ZAR" "MYR" "BRL" "RUB" "SEK" "IDR" "ISK" "MOP" "CNY" "TWD" "MXN" "EGP" "QAR" "SAR" "DKK" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BSD" "BTN" "BWP" "BYR" "BZD" "CDF" "CLP" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DOP" "DZD" "ERN" "ETB" "FJD" "FKP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HNL" "HRK" "HTG" "HUF" "ILS" "IMP" "IQD" "IRR" "JEP" "JMD" "JOD" "KES" "KGS" "KHR" "KMF" "KPW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MRO" "MUR" "MVR" "MWK" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "RON" "RSD" "RWF" "SBD" "SCR" "SDG" "SHP" "SLL" "SOS" "SPL" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TZS" "UAH" "UGX" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XCD" "XDR" "XOF" "XPF" "YER" "ZMW" "ZWD"

Currency code for product pricing.
fetch-variants
boolean

Flag to fetch product variants.
language
string
Default: "EN"
Enum: "EN" "ES" "FR" "IT" "DE" "PT" "NL" "PL"
Example: language=EN

Language code for localization.

Responses

Request samples 

curl --location 'https://www.headout.com/api/v1/product/get/3336?currencyCode=EUR&language=PT&fetch-variants=true' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "canonicalUrl": "string",
  • "content": {
    },
  • "city": {
    },
  • "media": [
    ],
  • "startLocation": {
    },
  • "endLocation": {
    },
  • "address": {
    },
  • "productType": "string",
  • "reviewsSummary": {
    },
  • "pricing": {
    },
  • "listingPrice": {
    },
  • "currency": {
    },
  • "localeSpecificUrls": {
    },
  • "hasInstantConfirmation": true,
  • "hasMobileTicket": true,
  • "primaryCategory": {
    },
  • "primarySubCategory": {
    },
  • "primaryCollection": {
    },
  • "variants": [
    ],
  • "cancellationPolicy": {
    },
  • "reschedulePolicy": {
    },
  • "pois": [
    ],
  • "cutoffTimeInMinutes": 0,
  • "inventorySelectionType": "string"
}

List product listing by city

GET /product/listing/list-by/city

List product listing using city.

Request

MODE KEY TYPE OPTIONAL DESCRIPTION
QUERY cityCode string no The city code. Eg: NEW_YORK, DUBAI
QUERY currencyCode string yes The currency in which pricing information will be returned. Eg: USD, AED. Ref: https://en.wikipedia.org/wiki/ISO_4217
QUERY language string yes (Default: EN) The language in which the product details will be returned. Eg: EN, ES, FR, IT, DE, PT, NL
QUERY offset string yes The offset for pagination. Ref: Pagination - Request Params
QUERY limit int yes The limit for pagination. Ref: Pagination - Request Params

Response

Response Example 
{
  "items": [
    {
      "id": "2844",
      "name": "Fast Track Tickets to the London Eye",
      "url": "/london-eye-tickets/fast-track-tickets-to-the-london-eye-e-2844/",
      "canonicalUrl": "https://www.headout.com/london-eye-tickets/fast-track-tickets-to-the-london-eye-e-2844/",
      "city": {
        "name": "London",
        "code": "LONDON"
      },
      "image": {
        "url": "https://cdn-imgix.headout.com/tour/4407/TOUR-IMAGE/12d3a2c5-a39e-4f0f-9724-dcd63f5429cb-2844-london-london-eye--fast-track-entry-tickets-04.jpg"
      },
      "neighbourhood": null,
      "primaryCategory": {
        "id": 279,
        "name": "London Eye Tickets",
        "cityCode": "LONDON",
        "url": "/category/279"
      },
      "currency": {
        "code": "USD",
        "currencyName": "United States Dollar",
        "symbol": "US$",
        "localSymbol": "$",
        "precision": 2,
        "currency": "USD"
      },
      "startGeolocation": {
        "latitude": 51.50345230102539,
        "longitude": -0.119518555700779
      },
      "ratingCumulative": {
        "avg": 4.47,
        "count": 3398
      },
      "pricing": {
        "type": "PER_PERSON",
        "currencyCode": "USD",
        "minimumPrice": {
          "originalPrice": 58.4,
          "finalPrice": 58.4
        },
        "bestDiscount": 0
      },
      "hasInstantConfirmation": true
    }
  ],
  "nextUrl": "https://www.headout.com/api/v1/product/listing/list-by/city?cityCode=LONDON&currencyCode=USD&language=EN&offset=11&limit=1",
  "prevUrl": "https://www.headout.com/api/v1/product/listing/list-by/city?cityCode=LONDON&currencyCode=USD&language=EN&offset=9&limit=1",
  "total": 224,
  "nextOffset": 11
}
Authorizations:
apiKeyAuth
query Parameters
cityCode
required
string

City code to list product listings for.
currencyCode
string
Enum: "EUR" "GBP" "AED" "USD" "SGD" "AUD" "THB" "INR" "HKD" "KRW" "CAD" "JPY" "NZD" "CHF" "ZAR" "MYR" "BRL" "RUB" "SEK" "IDR" "ISK" "MOP" "CNY" "TWD" "MXN" "EGP" "QAR" "SAR" "DKK" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BSD" "BTN" "BWP" "BYR" "BZD" "CDF" "CLP" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DOP" "DZD" "ERN" "ETB" "FJD" "FKP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HNL" "HRK" "HTG" "HUF" "ILS" "IMP" "IQD" "IRR" "JEP" "JMD" "JOD" "KES" "KGS" "KHR" "KMF" "KPW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MRO" "MUR" "MVR" "MWK" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "RON" "RSD" "RWF" "SBD" "SCR" "SDG" "SHP" "SLL" "SOS" "SPL" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TZS" "UAH" "UGX" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XCD" "XDR" "XOF" "XPF" "YER" "ZMW" "ZWD"

Currency code for product pricing.
language
string
Default: "EN"
Enum: "EN" "ES" "FR" "IT" "DE" "PT" "NL" "PL"
Example: language=EN

Language code for localization.
offset
string

Number of items to skip before starting to collect the result set.
limit
integer

Maximum number of items to return.

Responses

Request samples 

curl --location 'https://www.headout.com/api/v1/product/listing/list-by/city?cityCode=LONDON&currencyCode=CAD&language=FR&limit=10&offset=10' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

List product listing by category

GET /product/listing/list-by/category

List product listing using category.

Request

MODE KEY TYPE OPTIONAL DESCRIPTION
QUERY categoryId string no The id of the category.
QUERY language string yes (Default: EN) The language in which the product details will be returned. Eg: EN, ES, FR, IT, DE, PT, NL
QUERY currencyCode string yes The currency in which pricing information will be returned. Eg: USD, AED. Ref: https://en.wikipedia.org/wiki/ISO_4217
QUERY limit int yes The limit for pagination. Ref: Pagination - Request Params
QUERY offset string yes The offset for pagination. Ref: Pagination - Request Params

Response

Response Example 
{
  "items": [
    {
      "id": "11228",
      "name": "Tickets to Khao Kheow Open Zoo",
      "url": "/es/khao-kheow-open-zoo/khao-kheow-open-zoo-e-11228/",
      "canonicalUrl": "https://www.headout.com/es/khao-kheow-open-zoo/khao-kheow-open-zoo-e-11228/",
      "city": {
        "name": "Pattaya",
        "code": "PATTAYA"
      },
      "image": {
        "url": "https://cdn-imgix.headout.com/tour/21259/TOUR-IMAGE/4dd55cf1-4beb-45ad-aa50-7d6b8b58ca39-11228-pattaya-khao-kheow-open-zoo-01.jpg"
      },
      "neighbourhood": null,
      "primaryCategory": {
        "id": 4842,
        "name": "Khao Kheow Open Zoo",
        "cityCode": "PATTAYA",
        "url": "/category/4842"
      },
      "currency": {
        "code": "EUR",
        "currencyName": "Euro",
        "symbol": "EUR",
        "localSymbol": "€",
        "precision": 2,
        "currency": "EUR"
      },
      "startGeolocation": {
        "latitude": 13.214982986450195,
        "longitude": 101.05597686767578
      },
      "ratingCumulative": {
        "avg": 4.44,
        "count": 2023
      },
      "pricing": {
        "type": "PER_PERSON",
        "currencyCode": "EUR",
        "minimumPrice": {
          "originalPrice": 6.51,
          "finalPrice": 5.73
        },
        "bestDiscount": 12
      },
      "hasInstantConfirmation": true
    }
  ],
  "nextUrl": "https://www.headout.com/api/v1/product/listing/list-by/category?categoryId=3956&language=ES&currencyCode=EUR&offset=11&limit=1",
  "prevUrl": "https://www.headout.com/api/v1/product/listing/list-by/category?categoryId=3956&language=ES&currencyCode=EUR&offset=9&limit=1",
  "total": 25,
  "nextOffset": 11
}
Authorizations:
apiKeyAuth
query Parameters
categoryId
required
string

Category ID to list product listings for.
language
string
Default: "EN"
Enum: "EN" "ES" "FR" "IT" "DE" "PT" "NL" "PL"
Example: language=EN

Language code for localization.
currencyCode
string
Enum: "EUR" "GBP" "AED" "USD" "SGD" "AUD" "THB" "INR" "HKD" "KRW" "CAD" "JPY" "NZD" "CHF" "ZAR" "MYR" "BRL" "RUB" "SEK" "IDR" "ISK" "MOP" "CNY" "TWD" "MXN" "EGP" "QAR" "SAR" "DKK" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BSD" "BTN" "BWP" "BYR" "BZD" "CDF" "CLP" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DOP" "DZD" "ERN" "ETB" "FJD" "FKP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HNL" "HRK" "HTG" "HUF" "ILS" "IMP" "IQD" "IRR" "JEP" "JMD" "JOD" "KES" "KGS" "KHR" "KMF" "KPW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MRO" "MUR" "MVR" "MWK" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "RON" "RSD" "RWF" "SBD" "SCR" "SDG" "SHP" "SLL" "SOS" "SPL" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TZS" "UAH" "UGX" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XCD" "XDR" "XOF" "XPF" "YER" "ZMW" "ZWD"

Currency code for product pricing.
offset
string

Number of items to skip before starting to collect the result set.
limit
integer

Maximum number of items to return.

Responses

Request samples 

curl --location 'https://www.headout.com/api/v1/product/listing/list-by/category?categoryId=3956&language=ES&currencyCode=EUR&limit=20&offset=10' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

List all products

GET /products

Overview

The Partner Products API v2 provides endpoints for accessing the products. This API is designed to facilitate partners in fetching relevant product information for different cities and languages.

Request

API Parameters

Parameter Required / Optional Description Default Value
cityCode Required The city code to fetch products for.
collectionId Optional Collection ID to filter products.
categoryId Optional Category ID to filter products.
subCategoryId Optional Subcategory ID to filter products.
languageCode Optional Language code. EN
currencyCode Optional Currency code.
campaignName Optional Campaign name for filtering.
offset Optional Offset for pagination. 0
limit Optional Limit for pagination. 20

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Note: The pricing object fields vary by partner type. Both fields are shown in the response example below for reference.

Pricing for API Partners and Agent Partners:

"pricing": {
    "currency": "USD",
    "profileType": "PER_PERSON",
    "headoutSellingPrice": 41.00,
    "netPrice": 33.62
}

Pricing for Affiliates:

"pricing": {
    "currency": "USD",
    "profileType": "PER_PERSON",
    "headoutSellingPrice": 41.00,
    "commissionAmount": 4.10
}
Response Example 
{
  "products": [
    {
      "id": "700",
      "name": "American Museum of Natural History Tickets",
      "canonicalUrl": "https://sandbox.deimos.dev-headout.com/american-museum-of-natural-history-tickets/american-museum-of-natural-history-tickets-e-700/?affiliate_code=...",
      "city": {
        "code": "NEW_YORK",
        "name": "New York",
        "image": {
          "url": "//cdn-imgix.headout.com/media/images/ee075882083344be170ed38c8c76b4a1-new-york-city-01.jpeg"
        }
      },
      "content": {
        "highlights": "- Explore the largest dinosaur fossil collection, including *T. rex*, Apatosaurus, and a 122-foot ti...",
        "inclusions": "- Entry to the American Museum of Natural History \r\n\r\n**Access to** \r\n\r\n- Over 40 permanent gallerie...",
        "exclusions": "",
        "shortSummary": "Visit one of NYC\u2019s top destinations, the American Museum of Natural History, and explore its renowne...",
        "highlightsHtml": "<ul>\n<li>\n<p>Explore the largest dinosaur fossil collection, including <em>T. rex</em>, Apatosaurus,...",
        "inclusionsHtml": "<ul>\n<li>Entry to the American Museum of Natural History</li>\n</ul>\n<p><strong>Access to</strong></p...",
        "exclusionsHtml": "",
        "summaryHtml": "<h2>Your experience</h2>\n<p>Discover the wonders of the natural world at the American Museum of Natu...",
        "faqHtml": "<h2>Know before you go</h2>\n<h3>What's not allowed</h3>\n<ul>\n<li>\n<p>Keep in mind food, drinks, lugg...",
        "ticketDeliveryInfoHtml": "<ul>\n<li>\n<p>Your voucher will be emailed to you instantly.</p>\n</li>\n<li>\n<p>This attraction requir..."
      },
      "media": [
        {
          "url": "https://cdn-imgix.headout.com/media/images/330df44d-508a-43aa-8342-4b898f59f407-1749725345083-283951.jpg",
          "type": "IMAGE"
        },
        {
          "url": "https://cdn-imgix.headout.com/media/images/2e218cb6-d29e-4820-bc5b-f04c66a7f2e1-1749725341577-283950.jpg",
          "type": "IMAGE"
        }
      ],
      "startLocation": {
        "address": "American Museum of Natural History, 200 Central Park W, New York, New York",
        "city": "NEW_YORK",
        "postalCode": "10024",
        "country": "United States",
        "latitude": 40.78132247924805,
        "longitude": -73.97399139404297
      },
      "endLocation": {
        "address": null,
        "city": "NEW_YORK",
        "postalCode": null,
        "country": "",
        "latitude": 40.78132247924805,
        "longitude": -73.97399139404297
      },
      "productType": "ATTRACTION",
      "reviewsSummary": {
        "ratingsCount": 2275,
        "averageRating": 4.4
      },
      "pricing": {
        "currency": "USD",
        "profileType": "PER_PERSON",
        "headoutSellingPrice": 37.0,
        "netPrice": 26.94
      },
      "listingPrice": {
        "type": "PER_PERSON",
        "currencyCode": "USD",
        "minimumPrice": {
          "originalPrice": 37.0,
          "finalPrice": 26.94
        },
        "bestDiscount": 0
      },
      "currency": {
        "code": "USD",
        "currencyName": "United States Dollar",
        "symbol": "US$",
        "localSymbol": "$",
        "precision": 2,
        "currency": "USD"
      },
      "localeSpecificUrls": {
        "EN": "/american-museum-of-natural-history-tickets/american-museum-of-natural-history-tickets-e-700/",
        "ES": "/es/entradas-museo-americano-de-historia-natural/entradas-museo-americano-de-historia-natural-e-700/",
        "FR": "/fr/musee-americain-dhistoire-naturelle/billets-du-musee-americain-dhistoire-naturelle-e-700/",
        "IT": "/it/biglietti-per-il-museo-americano-di-storia-naturale/biglietti-per-il-museo-americano-di-storia-naturale-e-700/",
        "DE": "/de/amerikanisches-museum-fur-naturgeschichte-tickets/amerikanisches-museum-fur-naturgeschichte-tickets-e-700/"
      },
      "hasInstantConfirmation": false,
      "hasMobileTicket": false,
      "primaryCategory": {
        "id": "1",
        "name": "Tickets",
        "localeSpecificUrls": {
          "EN": "/tickets-new_york-ca-1~21553/",
          "ES": "/es/entradas-new_york-ca-1~21553/",
          "FR": "/fr/billets-new_york-ca-1~21553/",
          "IT": "/it/biglietti-new_york-ca-1~21553/",
          "DE": "/de/tickets-new_york-ca-1~21553/"
        },
        "canonicalUrl": "https://www.headout.com/tickets-new_york-ca-1~21553/"
      },
      "primarySubCategory": {
        "id": "1002",
        "name": "Museums",
        "categoryId": "1",
        "canonicalUrl": "https://www.headout.com/museums-new_york-sc-1002~21553/",
        "localeSpecificUrls": {
          "EN": "/museums-new_york-sc-1002~21553/",
          "ES": "/es/museos-new_york-sc-1002~21553/",
          "FR": "/fr/musees-new_york-sc-1002~21553/",
          "IT": "/it/musei-new_york-sc-1002~21553/",
          "DE": "/de/museen-new_york-sc-1002~21553/"
        }
      },
      "primaryCollection": {
        "id": "3544",
        "name": "American Museum of Natural History",
        "content": null,
        "cityCode": "NEW_YORK",
        "localeSpecificUrls": {},
        "canonicalUrl": "https://www.headout.com/american-museum-of-natural-history-tickets-c-3544/",
        "heroImage": null,
        "cardImage": null
      },
      "variants": [
        {
          "id": 881,
          "name": "General Admission",
          "description": "- Entry to the American Museum of Natural History \r\n- Access to: \r\n    - All permanent exhibits\r\n   ...",
          "duration": 3600000,
          "inventoryType": "FLEXIBLE_START_FLEXIBLE_DURATION",
          "pax": {
            "min": 1,
            "max": 10
          },
          "cashback": {
            "value": 0.0,
            "type": "PERCENTAGE"
          },
          "ticketDeliveryInfoHtml": null,
          "cancellationPolicy": {
            "cancellable": false,
            "cancellableUpTo": null
          },
          "meetingPointInfo": {
            "latitude": "40.7813240999999900",
            "longitude": "-73.9739882000000000",
            "address": "American Museum of Natural History, Central Park West, New York, NY, USA"
          },
          "inputFields": [
            {
              "oldId": 313,
              "id": "NAME",
              "name": "Full Name",
              "dataType": "STRING",
              "validation": {
                "regex": "\\s*[^\\s]+\\s+[^\\s]+.*",
                "minLength": 3,
                "maxLength": 80,
                "minValue": null,
                "maxValue": null,
                "required": true,
                "values": null
              },
              "level": "PRIMARY_CUSTOMER"
            },
            {
              "oldId": 4408,
              "id": "EMAIL",
              "name": "Email",
              "dataType": "STRING",
              "validation": {
                "regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
                "minLength": 5,
                "maxLength": null,
                "minValue": null,
                "maxValue": null,
                "required": true,
                "values": null
              },
              "level": "PRIMARY_CUSTOMER"
            },
            {
              "oldId": 8503,
              "id": "PHONE",
              "name": "Phone",
              "dataType": "STRING",
              "validation": {
                "regex": null,
                "minLength": null,
                "maxLength": 40,
                "minValue": null,
                "maxValue": null,
                "required": true,
                "values": null
              },
              "level": "PRIMARY_CUSTOMER"
            }
          ],
          "tags": [
            "ATTRACTION",
            "COMBO",
            "NYCATT",
            "NYCATT0",
            "SCHEDULE-90-DAYS"
          ],
          "properties": {},
          "propertiesV2": {}
        },
        {
          "id": 60261,
          "name": "General Admission + 1 Ticketed Experience",
          "description": "- Choice of entry to 1 of the following:\r\n    - The new butterfly vivarium\r\n    - Giant-screen film\r...",
          "duration": 3600000,
          "inventoryType": "FLEXIBLE_START_FLEXIBLE_DURATION",
          "pax": {
            "min": 1,
            "max": 10
          },
          "cashback": {
            "value": 0.0,
            "type": "PERCENTAGE"
          },
          "ticketDeliveryInfoHtml": null,
          "cancellationPolicy": {
            "cancellable": false,
            "cancellableUpTo": null
          },
          "meetingPointInfo": {
            "latitude": "40.7813240999999900",
            "longitude": "-73.9739882000000000",
            "address": "American Museum of Natural History, Central Park West, New York, NY, USA"
          },
          "inputFields": [
            {
              "oldId": 195346,
              "id": "NAME",
              "name": "Full Name",
              "dataType": "STRING",
              "validation": {
                "regex": "\\s*[^\\s]+\\s+[^\\s]+.*",
                "minLength": 3,
                "maxLength": 80,
                "minValue": null,
                "maxValue": null,
                "required": true,
                "values": null
              },
              "level": "PRIMARY_CUSTOMER"
            },
            {
              "oldId": 195347,
              "id": "EMAIL",
              "name": "Email",
              "dataType": "STRING",
              "validation": {
                "regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
                "minLength": 5,
                "maxLength": null,
                "minValue": null,
                "maxValue": null,
                "required": true,
                "values": null
              },
              "level": "PRIMARY_CUSTOMER"
            },
            {
              "oldId": 195348,
              "id": "PHONE",
              "name": "Phone",
              "dataType": "STRING",
              "validation": {
                "regex": null,
                "minLength": null,
                "maxLength": 40,
                "minValue": null,
                "maxValue": null,
                "required": true,
                "values": null
              },
              "level": "PRIMARY_CUSTOMER"
            }
          ],
          "tags": [],
          "properties": {},
          "propertiesV2": {}
        }
      ],
      "inventorySelectionType": "NORMAL",
      "cancellationPolicy": {
        "cancellable": false,
        "cancellableUpToInMinutes": null
      },
      "reschedulePolicy": {
        "reschedulable": false,
        "reschedulableUpToInMinutes": null
      }
    }
  ],
  "nextUrl": "/api/public/v2/products?cityCode=NEW_YORK&languageCode=EN&currencyCode=USD&offset=1&limit=1",
  "prevUrl": null,
  "total": 107,
  "nextOffset": 1
}

Notes

  • Ensure that all required parameters are included in your requests.
  • Use appropriate city and language codes as per your application requirements.
  • Pagination parameters (offset and limit) help in managing large datasets.
Authorizations:
apiKeyAuth
query Parameters
cityCode
required
string

The code of the city for which data is being requested.
collectionId
string

The ID of the collection.
categoryId
string

The ID of the category.
subCategoryId
string

The ID of the subcategory.
languageCode
string
Default: "EN"
Enum: "EN" "ES" "FR" "IT" "DE" "PT" "NL" "PL"

The language code for localization. Default is 'EN'.
currencyCode
string
Enum: "EUR" "GBP" "AED" "USD" "SGD" "AUD" "THB" "INR" "HKD" "KRW" "CAD" "JPY" "NZD" "CHF" "ZAR" "MYR" "BRL" "RUB" "SEK" "IDR" "ISK" "MOP" "CNY" "TWD" "MXN" "EGP" "QAR" "SAR" "DKK" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BSD" "BTN" "BWP" "BYR" "BZD" "CDF" "CLP" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DOP" "DZD" "ERN" "ETB" "FJD" "FKP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HNL" "HRK" "HTG" "HUF" "ILS" "IMP" "IQD" "IRR" "JEP" "JMD" "JOD" "KES" "KGS" "KHR" "KMF" "KPW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MRO" "MUR" "MVR" "MWK" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "RON" "RSD" "RWF" "SBD" "SCR" "SDG" "SHP" "SLL" "SOS" "SPL" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TZS" "UAH" "UGX" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XCD" "XDR" "XOF" "XPF" "YER" "ZMW" "ZWD"

The currency code for price information.
campaignName
string

The name of the campaign.
offset
string

The number of items to skip before starting to collect the result set.
limit
integer

The numbers of items to return.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v2/products?cityCode=<CITY_CODE>&collectionId=<COLLECTION_ID>&campaignName=<CAMPAIGN_NAME>&languageCode=<LANGUAGE_CODE>&currencyCode=<CURRENCY_CODE>&limit=<LIMIT>&offset=<OFFSET>' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "products": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

Fetch product by ID

GET /products/{productId}

Overview

The Partner Products API v2 provides endpoints for accessing the products. This API is designed to facilitate partners in fetching relevant product information for different cities and languages.

Request

API Parameters

Mode Parameter Required / Optional Description Default Value
PATH productId Required Product ID to fetch the details for.
QUERY languageCode Optional Language code. EN
QUERY currencyCode Optional Currency code.
QUERY campaignName Optional Campaign name for filtering.

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Note: The pricing object fields vary by partner type. Both fields are shown in the response example below for reference.

Pricing for API Partners and Agent Partners:

"pricing": {
    "currency": "USD",
    "profileType": "PER_PERSON",
    "headoutSellingPrice": 39.20,
    "netPrice": 32.14
}

Pricing for Affiliates:

"pricing": {
    "currency": "USD",
    "profileType": "PER_PERSON",
    "headoutSellingPrice": 39.20,
    "commissionAmount": 3.92
}
Response Example 
{
    "id": "700",
    "name": "American Museum of Natural History Tickets",
    "canonicalUrl": "https://sandbox.deimos.dev-headout.com/american-museum-of-natural-history-tickets/american-museum-of-natural-history-tickets-e-700/?affiliate_code=...",
    "city": {
        "code": "NEW_YORK",
        "name": "New York",
        "image": {
            "url": "//cdn-imgix.headout.com/media/images/ee075882083344be170ed38c8c76b4a1-new-york-city-01.jpeg"
        }
    },
    "content": {
        "highlights": "- Explore the largest dinosaur fossil collection, including *T. rex*, Apatosaurus, and a 122-foot ti...",
        "inclusions": "- Entry to the American Museum of Natural History \r\n\r\n**Access to** \r\n\r\n- Over 40 permanent gallerie...",
        "exclusions": "",
        "shortSummary": "Visit one of NYC\u2019s top destinations, the American Museum of Natural History, and explore its renowne...",
        "highlightsHtml": "<ul>\n<li>\n<p>Explore the largest dinosaur fossil collection, including <em>T. rex</em>, Apatosaurus,...",
        "inclusionsHtml": "<ul>\n<li>Entry to the American Museum of Natural History</li>\n</ul>\n<p><strong>Access to</strong></p...",
        "exclusionsHtml": "",
        "summaryHtml": "<h2>Your experience</h2>\n<p>Discover the wonders of the natural world at the American Museum of Natu...",
        "faqHtml": "<h2>Know before you go</h2>\n<h3>What's not allowed</h3>\n<ul>\n<li>\n<p>Keep in mind food, drinks, lugg...",
        "ticketDeliveryInfoHtml": "<ul>\n<li>\n<p>Your voucher will be emailed to you instantly.</p>\n</li>\n<li>\n<p>This attraction requir..."
    },
    "media": [
        {
            "url": "https://cdn-imgix.headout.com/media/images/330df44d-508a-43aa-8342-4b898f59f407-1749725345083-283951.jpg",
            "type": "IMAGE"
        },
        {
            "url": "https://cdn-imgix.headout.com/media/images/2e218cb6-d29e-4820-bc5b-f04c66a7f2e1-1749725341577-283950.jpg",
            "type": "IMAGE"
        },
        {
            "url": "https://cdn-imgix.headout.com/media/images/ef5755b0f050d8a42347f65f852a71c1-NWC-MFKEYIMAGEFINAL-MED-res.jpg",
            "type": "IMAGE"
        }
    ],
    "startLocation": {
        "address": "American Museum of Natural History, 200 Central Park W, New York, New York",
        "city": "NEW_YORK",
        "postalCode": "10024",
        "country": "United States",
        "latitude": 40.78132247924805,
        "longitude": -73.97399139404297
    },
    "endLocation": {
        "address": "American Museum of Natural History, 200 Central Park W, New York, New York",
        "city": "NEW_YORK",
        "postalCode": "10024",
        "country": "United States",
        "latitude": 40.78132247924805,
        "longitude": -73.97399139404297
    },
    "productType": "ATTRACTION",
    "reviewsSummary": {
        "ratingsCount": 2275,
        "averageRating": 4.4
    },
    "pricing": {
        "currency": "USD",
        "profileType": "PER_PERSON",
        "headoutSellingPrice": 37.0,
        "netPrice": 26.94
    },
    "listingPrice": {
        "type": "PER_PERSON",
        "currencyCode": "USD",
        "minimumPrice": {
            "originalPrice": 37.0,
            "finalPrice": 26.94
        },
        "bestDiscount": 0
    },
    "currency": {
        "code": "USD",
        "currencyName": "United States Dollar",
        "symbol": "US$",
        "localSymbol": "$",
        "precision": 2,
        "currency": "USD"
    },
    "localeSpecificUrls": {
        "EN": "/american-museum-of-natural-history-tickets/american-museum-of-natural-history-tickets-e-700/",
        "ES": "/es/entradas-museo-americano-de-historia-natural/entradas-museo-americano-de-historia-natural-e-700/",
        "FR": "/fr/musee-americain-dhistoire-naturelle/billets-du-musee-americain-dhistoire-naturelle-e-700/",
        "IT": "/it/biglietti-per-il-museo-americano-di-storia-naturale/biglietti-per-il-museo-americano-di-storia-naturale-e-700/",
        "DE": "/de/amerikanisches-museum-fur-naturgeschichte-tickets/amerikanisches-museum-fur-naturgeschichte-tickets-e-700/"
    },
    "hasInstantConfirmation": false,
    "hasMobileTicket": false,
    "primaryCategory": {
        "id": "1",
        "name": "Tickets",
        "localeSpecificUrls": {
            "EN": "/tickets-new_york-ca-1~21553/",
            "ES": "/es/entradas-new_york-ca-1~21553/",
            "FR": "/fr/billets-new_york-ca-1~21553/",
            "IT": "/it/biglietti-new_york-ca-1~21553/",
            "DE": "/de/tickets-new_york-ca-1~21553/"
        },
        "canonicalUrl": "https://www.headout.com/tickets-new_york-ca-1~21553/"
    },
    "primarySubCategory": {
        "id": "1002",
        "name": "Museums",
        "categoryId": "1",
        "canonicalUrl": "https://www.headout.com/museums-new_york-sc-1002~21553/",
        "localeSpecificUrls": {
            "EN": "/museums-new_york-sc-1002~21553/",
            "ES": "/es/museos-new_york-sc-1002~21553/",
            "FR": "/fr/musees-new_york-sc-1002~21553/",
            "IT": "/it/musei-new_york-sc-1002~21553/",
            "DE": "/de/museen-new_york-sc-1002~21553/"
        }
    },
    "primaryCollection": {
        "id": "3544",
        "name": "American Museum of Natural History",
        "content": null,
        "cityCode": "NEW_YORK",
        "localeSpecificUrls": {},
        "canonicalUrl": "https://www.headout.com/american-museum-of-natural-history-tickets-c-3544/",
        "heroImage": null,
        "cardImage": null
    },
    "variants": [
        {
            "id": 881,
            "name": "General Admission",
            "description": "- Entry to the American Museum of Natural History \r\n- Access to: \r\n    - All permanent exhibits\r\n   ...",
            "duration": 3600000,
            "inventoryType": "FLEXIBLE_START_FLEXIBLE_DURATION",
            "pax": {
                "min": 1,
                "max": 10
            },
            "cashback": {
                "value": 0.0,
                "type": "PERCENTAGE"
            },
            "ticketDeliveryInfoHtml": null,
            "cancellationPolicy": {
                "cancellable": false,
                "cancellableUpTo": null
            },
            "meetingPointInfo": {
                "latitude": "40.7813240999999900",
                "longitude": "-73.9739882000000000",
                "address": "American Museum of Natural History, Central Park West, New York, NY, USA"
            },
            "inputFields": [
                {
                    "oldId": 313,
                    "id": "NAME",
                    "name": "Full Name",
                    "dataType": "STRING",
                    "validation": {
                        "regex": "\\s*[^\\s]+\\s+[^\\s]+.*",
                        "minLength": 3,
                        "maxLength": 80,
                        "minValue": null,
                        "maxValue": null,
                        "required": true,
                        "values": null
                    },
                    "level": "PRIMARY_CUSTOMER"
                },
                {
                    "oldId": 4408,
                    "id": "EMAIL",
                    "name": "Email",
                    "dataType": "STRING",
                    "validation": {
                        "regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
                        "minLength": 5,
                        "maxLength": null,
                        "minValue": null,
                        "maxValue": null,
                        "required": true,
                        "values": null
                    },
                    "level": "PRIMARY_CUSTOMER"
                },
                {
                    "oldId": 8503,
                    "id": "PHONE",
                    "name": "Phone",
                    "dataType": "STRING",
                    "validation": {
                        "regex": null,
                        "minLength": null,
                        "maxLength": 40,
                        "minValue": null,
                        "maxValue": null,
                        "required": true,
                        "values": null
                    },
                    "level": "PRIMARY_CUSTOMER"
                }
            ],
            "tags": [
                "ATTRACTION",
                "COMBO",
                "NYCATT",
                "NYCATT0",
                "SCHEDULE-90-DAYS"
            ],
            "properties": {},
            "propertiesV2": {},
            "pricing": {
                "currency": "USD",
                "profileType": "PER_PERSON",
                "headoutSellingPrice": 37.0,
                "netPrice": 26.94
            }
        },
        {
            "id": 60261,
            "name": "General Admission + 1 Ticketed Experience",
            "description": "- Choice of entry to 1 of the following:\r\n    - The new butterfly vivarium\r\n    - Giant-screen film\r...",
            "duration": 3600000,
            "inventoryType": "FLEXIBLE_START_FLEXIBLE_DURATION",
            "pax": {
                "min": 1,
                "max": 10
            },
            "cashback": {
                "value": 0.0,
                "type": "PERCENTAGE"
            },
            "ticketDeliveryInfoHtml": null,
            "cancellationPolicy": {
                "cancellable": false,
                "cancellableUpTo": null
            },
            "meetingPointInfo": {
                "latitude": "40.7813240999999900",
                "longitude": "-73.9739882000000000",
                "address": "American Museum of Natural History, Central Park West, New York, NY, USA"
            },
            "inputFields": [
                {
                    "oldId": 195346,
                    "id": "NAME",
                    "name": "Full Name",
                    "dataType": "STRING",
                    "validation": {
                        "regex": "\\s*[^\\s]+\\s+[^\\s]+.*",
                        "minLength": 3,
                        "maxLength": 80,
                        "minValue": null,
                        "maxValue": null,
                        "required": true,
                        "values": null
                    },
                    "level": "PRIMARY_CUSTOMER"
                },
                {
                    "oldId": 195347,
                    "id": "EMAIL",
                    "name": "Email",
                    "dataType": "STRING",
                    "validation": {
                        "regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
                        "minLength": 5,
                        "maxLength": null,
                        "minValue": null,
                        "maxValue": null,
                        "required": true,
                        "values": null
                    },
                    "level": "PRIMARY_CUSTOMER"
                },
                {
                    "oldId": 195348,
                    "id": "PHONE",
                    "name": "Phone",
                    "dataType": "STRING",
                    "validation": {
                        "regex": null,
                        "minLength": null,
                        "maxLength": 40,
                        "minValue": null,
                        "maxValue": null,
                        "required": true,
                        "values": null
                    },
                    "level": "PRIMARY_CUSTOMER"
                }
            ],
            "tags": [],
            "properties": {},
            "propertiesV2": {},
            "pricing": {
                "currency": "USD",
                "profileType": "PER_PERSON",
                "headoutSellingPrice": 43.0,
                "netPrice": 31.3
            }
        }
    ],
    "inventorySelectionType": "NORMAL",
    "cancellationPolicy": {
        "cancellable": false,
        "cancellableUpToInMinutes": null
    },
    "reschedulePolicy": {
        "reschedulable": false,
        "reschedulableUpToInMinutes": null
    },
    "address": {
        "address": "American Museum of Natural History, 200 Central Park W, New York, New York",
        "city": "NEW_YORK",
        "country": "United States",
        "postalCode": "10024",
        "latitude": 40.78132247924805,
        "longitude": -73.97399139404297
    },
    "pois": [
        {
            "name": "American Museum of Natural History",
            "operatingSchedules": [
                {
                    "startDate": "2026-01-01",
                    "endDate": "2026-12-31",
                    "scheduleName": "All year",
                    "operatingDaySchedules": [
                        {
                            "dayOfWeek": "MONDAY",
                            "openingTime": "10:00",
                            "closingTime": "17:30",
                            "lastEntryTime": null,
                            "closed": false
                        },
                        {
                            "dayOfWeek": "TUESDAY",
                            "openingTime": "10:00",
                            "closingTime": "17:30",
                            "lastEntryTime": null,
                            "closed": false
                        }
                    ]
                }
            ],
            "holidays": [],
            "freeEntryDays": []
        }
    ],
    "cutoffTimeInMinutes": 0
}

Notes

  • Ensure that all required parameters are included in your requests.
  • Use appropriate language codes as per your application requirements.
Authorizations:
apiKeyAuth
query Parameters
languageCode
string
Default: "EN"
Enum: "EN" "ES" "FR" "IT" "DE" "PT" "NL" "PL"

The language code for localization. Default is 'EN'.
currencyCode
string
Enum: "EUR" "GBP" "AED" "USD" "SGD" "AUD" "THB" "INR" "HKD" "KRW" "CAD" "JPY" "NZD" "CHF" "ZAR" "MYR" "BRL" "RUB" "SEK" "IDR" "ISK" "MOP" "CNY" "TWD" "MXN" "EGP" "QAR" "SAR" "DKK" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BSD" "BTN" "BWP" "BYR" "BZD" "CDF" "CLP" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DOP" "DZD" "ERN" "ETB" "FJD" "FKP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HNL" "HRK" "HTG" "HUF" "ILS" "IMP" "IQD" "IRR" "JEP" "JMD" "JOD" "KES" "KGS" "KHR" "KMF" "KPW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MRO" "MUR" "MVR" "MWK" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "RON" "RSD" "RWF" "SBD" "SCR" "SDG" "SHP" "SLL" "SOS" "SPL" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TZS" "UAH" "UGX" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XCD" "XDR" "XOF" "XPF" "YER" "ZMW" "ZWD"

The currency code for price information.
campaignName
string

The name of the campaign.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v2/products/<PRODUCT_ID>?campaignName=<CAMPAIGN_NAME>&languageCode=<LANGUAGE_CODE>&currencyCode=<CURRENCY_CODE>' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "canonicalUrl": "string",
  • "content": {
    },
  • "city": {
    },
  • "media": [
    ],
  • "startLocation": {
    },
  • "endLocation": {
    },
  • "address": {
    },
  • "productType": "string",
  • "reviewsSummary": {
    },
  • "pricing": {
    },
  • "listingPrice": {
    },
  • "currency": {
    },
  • "localeSpecificUrls": {
    },
  • "hasInstantConfirmation": true,
  • "hasMobileTicket": true,
  • "primaryCategory": {
    },
  • "primarySubCategory": {
    },
  • "primaryCollection": {
    },
  • "variants": [
    ],
  • "cancellationPolicy": {
    },
  • "reschedulePolicy": {
    },
  • "pois": [
    ],
  • "cutoffTimeInMinutes": 0,
  • "inventorySelectionType": "string"
}

Category

Category operations

List all categories

GET /categories

Overview

The Partner Categories API v2 provides endpoints for accessing the categories. This API is designed to facilitate partners in fetching relevant data for different cities and languages.

Request

API Parameters

Parameter Required / Optional Description Default Value
cityCode Required The city code to fetch categories for.
languageCode Optional Language code. EN

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Response Example 
{
  "categories": [
    {
      "id": "1",
      "name": "Tickets",
      "localeSpecificUrls": {
        "EN": "/tickets-new_york-ca-1~21553/",
        "ES": "/es/entradas-new_york-ca-1~21553/",
        "FR": "/fr/billets-new_york-ca-1~21553/",
        "IT": "/it/biglietti-new_york-ca-1~21553/",
        "DE": "/de/tickets-new_york-ca-1~21553/",
        "PT": "/pt/ingressos-new_york-ca-1~21553/",
        "NL": "/nl/tickets-new_york-ca-1~21553/"
      },
      "canonicalUrl": "https://www.headout.com/tickets-new_york-ca-1~21553/"
    },
    {
      "id": "2",
      "name": "Tours",
      "localeSpecificUrls": {
        "EN": "/tours-new_york-ca-2~21553/",
        "ES": "/es/tours-new_york-ca-2~21553/",
        "FR": "/fr/visites-new_york-ca-2~21553/",
        "IT": "/it/tour-new_york-ca-2~21553/",
        "DE": "/de/touren-new_york-ca-2~21553/",
        "PT": "/pt/tours-new_york-ca-2~21553/",
        "NL": "/nl/tours-new_york-ca-2~21553/"
      },
      "canonicalUrl": "https://www.headout.com/tours-new_york-ca-2~21553/"
    },
    {
      "id": "3",
      "name": "Transportation",
      "localeSpecificUrls": {
        "EN": "/transportation-new_york-ca-3~21553/",
        "ES": "/es/traslados-new_york-ca-3~21553/",
        "FR": "/fr/transport-new_york-ca-3~21553/",
        "IT": "/it/trasferimenti-new_york-ca-3~21553/",
        "DE": "/de/transfer-new_york-ca-3~21553/",
        "PT": "/pt/transporte-new_york-ca-3~21553/",
        "NL": "/nl/vervoer-new_york-ca-3~21553/"
      },
      "canonicalUrl": "https://www.headout.com/transportation-new_york-ca-3~21553/"
    }
  ]
}

Notes

  • Ensure that all required parameters are included in your requests.
  • Use appropriate city and language codes as per your application requirements.
Authorizations:
apiKeyAuth
query Parameters
cityCode
required
string

The code of the city for which data is being requested.
languageCode
string
Default: "EN"
Enum: "EN" "ES" "FR" "IT" "DE" "PT" "NL" "PL"

The language code for localization. Default is 'EN'.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v2/categories?cityCode=<CITY_CODE>&languageCode=<LANGUAGE_CODE>' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

Subcategory

Subcategory operations

List all subcategories

GET /subcategories

Overview

The Partner Subcategories API v2 provides endpoints for accessing the subcategories. This API is designed to facilitate partners in fetching relevant data for different cities and languages.

Request

API Parameters

Parameter Required / Optional Description Default Value
cityCode Required The city code to fetch categories for.
languageCode Optional Language code. EN

API Headers

Header Required / Optional Description
Headout-Auth Required The Authorization Token.

Response

Object: SubCategory

Response Example 
{
  "subCategories": [
    {
      "id": "1002",
      "name": "Museums",
      "categoryId": "1",
      "canonicalUrl": "https://www.headout.com/museums-new_york-sc-1002~21553/",
      "localeSpecificUrls": {
        "EN": "/museums-new_york-sc-1002~21553/",
        "ES": "/es/museos-new_york-sc-1002~21553/",
        "FR": "/fr/musees-new_york-sc-1002~21553/",
        "IT": "/it/musei-new_york-sc-1002~21553/",
        "DE": "/de/museen-new_york-sc-1002~21553/",
        "PT": "/pt/museus-new_york-sc-1002~21553/",
        "NL": "/nl/musea-new_york-sc-1002~21553/"
      }
    },
    {
      "id": "1006",
      "name": "Religious Sites",
      "categoryId": "1",
      "canonicalUrl": "https://www.headout.com/religious-sites-new_york-sc-1006~21553/",
      "localeSpecificUrls": {
        "EN": "/religious-sites-new_york-sc-1006~21553/",
        "ES": "/es/sitios-religiosos-new_york-sc-1006~21553/",
        "FR": "/fr/site-religieux-new_york-sc-1006~21553/",
        "IT": "/it/siti-religiosi-new_york-sc-1006~21553/",
        "DE": "/de/religiose-statten-new_york-sc-1006~21553/",
        "PT": "/pt/locais-religiosos-new_york-sc-1006~21553/",
        "NL": "/nl/religieuze-plaatsen-new_york-sc-1006~21553/"
      }
    },
    {
      "id": "1007",
      "name": "Landmarks",
      "categoryId": "1",
      "canonicalUrl": "https://www.headout.com/landmarks-new_york-sc-1007~21553/",
      "localeSpecificUrls": {
        "EN": "/landmarks-new_york-sc-1007~21553/",
        "ES": "/es/principales-atracciones-new_york-sc-1007~21553/",
        "FR": "/fr/monuments-new_york-sc-1007~21553/",
        "IT": "/it/punti-di-interesse-new_york-sc-1007~21553/",
        "DE": "/de/wahrzeichen-new_york-sc-1007~21553/",
        "PT": "/pt/marcos-historicos-new_york-sc-1007~21553/",
        "NL": "/nl/bezienswaardigheden-new_york-sc-1007~21553/"
      }
    }
  ]
}

Error Handling

Refer to this document for handling errors in the APIs.

Notes

  • Ensure that all required parameters are included in your requests.
  • Use appropriate city and language codes as per your application requirements.
Authorizations:
apiKeyAuth
query Parameters
cityCode
required
string

The code of the city for which data is being requested.
languageCode
string
Default: "EN"
Enum: "EN" "ES" "FR" "IT" "DE" "PT" "NL" "PL"

The language code for localization. Default is 'EN'.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v2/subcategories?cityCode=<CITY_CODE>&languageCode=<LANGUAGE_CODE>' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "subCategories": [
    ]
}

Inventory

Inventory operations

List inventory by tour

GET /inventory/list-by/tour

Get the available inventory for a tour within a specified date range.

Request

MODE KEY TYPE OPTIONAL DESCRIPTION
QUERY tourId string no The unique identifier of the tour for which the inventory needs to be fetched.
QUERY startDateTime string no The start date time from which the inventory needs to be fetched. Format: fm-date-time. Ref: inventory.startDateTime
QUERY endDateTime string no The end date time till which the inventory needs to be fetched. Format: fm-date-time. Ref: inventory.startDateTime
QUERY currencyCode string no The currency in which pricing information will be returned. Eg: EUR, USD, GBP. Ref: https://en.wikipedia.org/wiki/ISO_4217
QUERY offset string yes The offset for pagination.
QUERY limit int yes The limit for pagination.

Response

Response Example 
{
    "items": [
        {
            "id": "450931848",
            "startDateTime": "2025-07-25T11:30:00",
            "endDateTime": "2025-07-25T18:30:00",
            "availability": "UNLIMITED",
            "remaining": 6,
            "pricing": {
                "persons": [
                    {
                        "type": "ADULT",
                        "name": "Adult",
                        "description": "Above 8 Years",
                        "ageFrom": null,
                        "ageTo": null,
                        "price": 38.04,
                        "originalPrice": 43.29,
                        "netPrice": 38.04,
                        "headoutSellingPrice": 43.29,
                        "remaining": 200,
                        "availability": "LIMITED",
                        "paxRange": { "min": null, "max": 8 }
                    },
                    {
                        "type": "CHILD",
                        "name": "Child",
                        "description": null,
                        "ageFrom": 3,
                        "ageTo": 8,
                        "price": 29.66,
                        "originalPrice": 33.76,
                        "netPrice": 29.66,
                        "headoutSellingPrice": 33.76,
                        "remaining": 200,
                        "availability": "LIMITED",
                        "paxRange": { "min": null, "max": 8 }
                    }
                ],
                "groups": [
                    {
                        "size": 4,
                        "price": 120.00,
                        "originalPrice": 140.00,
                        "netPrice": 118.00,
                        "headoutSellingPrice": 120.00,
                        "remaining": 2,
                        "availability": "LIMITED"
                    }
                ]
            }
        }
    ],
    "nextUrl": "https://sandbox.api.dev-headout.com:443/api/public/v2/inventory/list-by/tour?tourId=52850&startDateTime=2025-07-25T00%3A00&endDateTime=2025-07-27T00%3A00&currencyCode=EUR&offset=1&limit=1",
    "prevUrl": null,
    "total": 28,
    "nextOffset": 1
}
Authorizations:
apiKeyAuth
query Parameters
tourId
required
string

The unique identifier of the tour
startDateTime
required
string <date-time>

Start date and time in ISO 8601 format (URL encoded)
endDateTime
required
string <date-time>

End date and time in ISO 8601 format (URL encoded)
currencyCode
string
Enum: "EUR" "GBP" "AED" "USD" "SGD" "AUD" "THB" "INR" "HKD" "KRW" "CAD" "JPY" "NZD" "CHF" "ZAR" "MYR" "BRL" "RUB" "SEK" "IDR" "ISK" "MOP" "CNY" "TWD" "MXN" "EGP" "QAR" "SAR" "DKK" "AFN" "ALL" "AMD" "ANG" "AOA" "ARS" "AWG" "AZN" "BAM" "BBD" "BDT" "BGN" "BHD" "BIF" "BMD" "BND" "BOB" "BSD" "BTN" "BWP" "BYR" "BZD" "CDF" "CLP" "COP" "CRC" "CUC" "CUP" "CVE" "CZK" "DJF" "DOP" "DZD" "ERN" "ETB" "FJD" "FKP" "GEL" "GGP" "GHS" "GIP" "GMD" "GNF" "GTQ" "GYD" "HNL" "HRK" "HTG" "HUF" "ILS" "IMP" "IQD" "IRR" "JEP" "JMD" "JOD" "KES" "KGS" "KHR" "KMF" "KPW" "KWD" "KYD" "KZT" "LAK" "LBP" "LKR" "LRD" "LSL" "LTL" "LVL" "LYD" "MAD" "MDL" "MGA" "MKD" "MMK" "MNT" "MRO" "MUR" "MVR" "MWK" "MZN" "NAD" "NGN" "NIO" "NOK" "NPR" "OMR" "PAB" "PEN" "PGK" "PHP" "PKR" "PLN" "PYG" "RON" "RSD" "RWF" "SBD" "SCR" "SDG" "SHP" "SLL" "SOS" "SPL" "SRD" "SSP" "STD" "SVC" "SYP" "SZL" "TJS" "TMT" "TND" "TOP" "TRY" "TTD" "TVD" "TZS" "UAH" "UGX" "UYU" "UZS" "VEF" "VND" "VUV" "WST" "XAF" "XCD" "XDR" "XOF" "XPF" "YER" "ZMW" "ZWD"

The currency code for price information.
offset
string

The number of items to skip before starting to collect the result set.
limit
integer

The numbers of items to return.

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v2/inventory/list-by/tour?tourId=52850&startDateTime=2025-07-25T00%3A00&endDateTime=2025-07-27T00%3A00&currencyCode=EUR&offset=0&limit=1' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "nextUrl": "string",
  • "prevUrl": "string",
  • "total": 0,
  • "nextOffset": 0
}

Webhooks

Webhook operations

Create webhook configuration

Booking Status Webhooks

Overview

Booking status webhooks provide real-time notifications when booking statuses change in the Headout system. Receive instant updates for booking confirmations, cancellations, and completions.

Booking Status Lifecycle

Status Definitions

Status Description Webhook Trigger
PENDING Booking is pending fulfillment ✅ On capture
COMPLETED Booking completed successfully ✅ On completion
CANCELLED Booking has been cancelled ✅ On cancellation
FAILED Booking failed due to payment or system errors ✅ On failure

Webhook Payload Structure

Standard Payload

{
  "bookingId": 123456789,
  "status": "COMPLETED",
  "eventTimestamp": "2024-01-15T10:30:00"
}

Payload Fields

Field Type Required Description
bookingId number ✅ Unique booking identifier (corresponds to itinerary ID)
status string ✅ Current booking status from ItineraryStatus enum
eventTimestamp string ✅ ISO 8601 timestamp when status change occurred (local time)

Implementation Guide

Webhook Configuration

  • Configure your webhook endpoint URL through the Headout Partner API
  • Ensure your endpoint accepts POST requests with JSON payload
  • Return HTTP 2xx status codes for successful processing
  • Return HTTP 5xx for temporary failures (will trigger retries)
  • Return HTTP 4xx for permanent failures (no retries)

Endpoint Requirements

  • HTTPS Only: All webhook URLs must use HTTPS protocol
  • Response Time: Respond within 30 seconds to avoid timeouts
  • Idempotency: Handle potential duplicate deliveries gracefully
  • Error Handling: Implement proper error responses

Example Payloads

Booking Captured 
{
  "bookingId": 987654321,
  "status": "PENDING",
  "eventTimestamp": "2024-01-15T14:22:33"
}
Booking Completed 
{
  "bookingId": 987654321,
  "status": "COMPLETED",
  "eventTimestamp": "2024-01-15T14:25:18"
}
Booking Cancelled 
{
  "bookingId": 987654321,
  "status": "CANCELLED",
  "eventTimestamp": "2024-01-16T09:15:42"
}
Booking Failed 
{
  "bookingId": 987654321,
  "status": "FAILED",
  "eventTimestamp": "2024-01-15T14:23:05"
}

Best Practices

Performance

  • Respond to webhooks within 30 seconds
  • Process webhooks asynchronously when possible
  • Use appropriate HTTP status codes

Notes

  • Webhooks are retried up to 4 times with exponential backoff
  • Use the Partner API to manage webhook configurations
  • Contact support for webhook delivery troubleshooting
Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri> [ 1 .. 2048 ] characters ^https://.*

HTTPS URL where webhooks will be delivered (must use HTTPS)
enabled
boolean
Default: true

Whether the webhook is active

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "timestamp": 1756977070403,
  • "message": "Webhook configuration created successfully"
}

Get webhook configuration

Retrieve your current webhook configuration

Authorizations:
apiKeyAuth

Responses

Request samples 

curl --location 'https://www.headout.com/api/public/v2/webhooks/' \
--header 'Headout-Auth: <YOUR_API_KEY>'

Response samples

Content type
application/json
{ }

Update webhook configuration

Update your existing webhook configuration

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
url
required
string <uri> ^https://.*

HTTPS URL where webhooks will be delivered (must use HTTPS)
enabled
boolean
Default: true

Whether the webhook is active

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "timestamp": 1756977149760,
  • "message": "Webhook configuration updated successfully"
}

Glossary

This section defines standard ENUMs and error codes used across Headout APIs. Developers should use these as reference values when integrating.

Overview

The Headout API uses standardized ENUMs and error codes to ensure consistent data structures and error handling across all endpoints. This glossary serves as a comprehensive reference for developers implementing Headout API integrations.

ENUMs

Language Codes

Supported language codes for API localization.

Code Language
EN English
ES Spanish
FR French
IT Italian
DE German
PT Portuguese
NL Dutch
PL Polish

Currency Codes

Supported currencies follow the ISO 4217 standard. Any currency listed in the ISO 4217 specification is supported.

City Codes

Supported cities are returned dynamically by the City API. This list may change over time, so always handle cities dynamically rather than hardcoding values.

Media Types

Supported media types in product details.

Type Description
IMAGE Image media
VIDEO Video media
PDF PDF document

Product Types

Supported product types within product details.

Type
TOUR
ACTIVITY
EVENT
ATTRACTION
TRANSFER
AIRPORT_TRANSFER
ADD_ON

Listing Price Types

Pricing types used in product listings.

Type Description
PER_PERSON Price per individual person
PER_GROUP Price for entire group

Inventory Types

Variant inventory types for booking management.

Type Description
FIXED_START_FIXED_DURATION Fixed start time and duration
FIXED_START_FLEXIBLE_DURATION Fixed start time, flexible duration
FLEXIBLE_START_FIXED_DURATION Flexible start time, fixed duration
FLEXIBLE_START_FLEXIBLE_DURATION Flexible start time and duration

Input Field Types

Input field types for variant-specific customer information.

Field Description
NAME Customer name
EMAIL Email address
PHONE Phone number
ADDRESS Address information
AGE_ Age-related fields
COUNTRY_ Country information
DATE_OF_BIRTH_ Date of birth
DROP_OFF_LOCATION_ Drop-off location
FULL_NAME_ Full name fields
GENDER_ Gender information
IDENTITY_DOCUMENT_DETAILS_ ID document details
LANGUAGE_ Language preference
NATIONALITY_ Nationality
PASSPORT_DETAILS_ Passport information
PHYSICAL_INFORMATION_-_HEIGHT_ Physical characteristics
PICK_UP_DETAILS_ Pickup information
PICKUP_LOCATION Pickup location
CUSTOM_* Custom dynamic fields provided by supply partners

Note: Many more values may appear dynamically from supply partners. Always handle unknown values gracefully.

Input Field Data Types

Data types an input field can have. Use this to drive form validation and rendering on your end.

Data Type Description Validation
STRING Free-form text (e.g., John Doe) Apply regex, minLength, maxLength from the validation object if present
ENUM One of a predefined set of string literals (e.g., MALE, FEMALE, OTHER) Value must be one of the entries in validation.values (always string[] for this type)
BOOL Boolean flag — submit as the string "true" or "false" —
INT Whole-number value (e.g., 25) Apply minValue, maxValue from validation if present
FLOAT Decimal number (e.g., 25.50) Apply minValue, maxValue from validation if present
LOCATION Pickup or drop-off location. When validation.values is non-empty, items are predefined location objects (not strings) — the customer must select one. When validation.values is null, accept a free-form address string. See predefined location object shape below

validation.values — Polymorphic Field

The type of items in validation.values depends on the field's dataType:

ENUM — validation.values is string[]. The submitted value must be an exact match.

"values": ["VEGETARIAN", "VEGAN", "GLUTEN_FREE", "NONE"]

LOCATION with predefined options — validation.values is an array of location objects. Render these as a dropdown and submit the selected object's id as the field value.

"values": [
  {
    "id": 24698,
    "latitude": 36.112946,
    "longitude": -115.176507,
    "address": "3600 S Las Vegas Blvd, Las Vegas, NV 89109, USA",
    "displayName": "Bellagio",
    "timingConfig": {
      "startTime": "10:30",
      "endTime": "11:00",
      "minPeriod": null,
      "maxPeriod": null
    },
    "note": null
  }
]

All other types — validation.values is null.

Predefined Location Object Fields

Field Type Description
id integer Unique identifier for this location. Submit this as the field value when creating a booking.
latitude number Latitude of the pickup/drop-off point in decimal degrees.
longitude number Longitude of the pickup/drop-off point in decimal degrees.
address string Full street address of the location.
displayName string Short human-readable label for display in a dropdown (e.g., "Bellagio").
timingConfig.startTime string | null Earliest pickup time for this location (HH:mm format). Null if no restriction.
timingConfig.endTime string | null Latest pickup time for this location (HH:mm format). Null if no restriction.
timingConfig.minPeriod integer | null Minimum notice required for this pickup in minutes. Null if no restriction.
timingConfig.maxPeriod integer | null Maximum advance booking window in minutes. Null if no restriction.
note object | null Additional instruction for this pickup location. Null if no note. Contains content (string) and language (language code).

Person Types

Person types valid for booking variants.

Type
ADULT
CHILD
INFANT
SENIOR
GENERAL
STUDENT
YOUTH

Note: Additional types such as RESIDENT, NON_EUR_CHILD, etc. may appear dynamically.

Cashback Types

Cashback value types for promotional offers.

Type Description
PERCENTAGE Percentage-based cashback
ABSOLUTE Fixed amount cashback

Inventory Selection Types

Inventory selection types for booking interfaces.

Type Description
NORMAL Standard selection interface
SEATMAP Seat map selection interface

Inventory Availability

Availability status within inventory slots.

Status Description
UNLIMITED Unlimited availability
LIMITED Limited availability
CLOSED No availability

Booking Status

Booking lifecycle statuses.

Status Description
UNCAPTURED Booking created but not yet captured
PENDING Captured, waiting for fulfillment
COMPLETED Booking fulfilled successfully
CANCELLED Booking was cancelled
FAILED Booking failed (payment/system error)
CAPTURE_TIMEDOUT Capture did not happen within allowed time

Cancellation Detail Reasons

Permitted cancellation reasons for partner cancellation requests.

Value Description
TICKETS_NOT_RECEIVED Tickets or voucher not received by the customer
CHANGE_OF_TRAVEL_PLANS Customer changed travel plans
MODIFY_EXISTING_RESERVATION Customer wants to modify an existing reservation
FOUND_CHEAPER_OPTION_ELSEWHERE Customer found a cheaper alternative
OTHER Other reason not listed above

Error Codes

Generic Errors

Code Category Description
CAL_0000 Generic Unknown error occurred

Cart Error Codes

Code Category Description
CAL_0100 Itinerary Unknown error occurred

Legitimacy Issues

Code Category Description
CAL_0101 Itinerary Tour information is not legitimate
CAL_0102 Itinerary Tour or language does not exist
CAL_0103 Itinerary Tour's addon does not exist
CAL_0104 Itinerary Price information is not legitimate
CAL_0105 Itinerary Itinerary item does not exist
CAL_0106 Itinerary Price of the item has changed
CAL_0107 Itinerary No ADULT in free booking
CAL_0108 Itinerary Children not permitted without adult
CAL_0109 Itinerary Minimum number of tickets not selected
CAL_0110 Itinerary Maximum number of tickets exceeded
CAL_0111 Itinerary Max 2 children per 1 Adult/Student/Senior
CAL_0112 Itinerary Minimum number of pax not selected
CAL_0113 Itinerary Maximum number of pax exceeded
CAL_0114 Itinerary Book now pay later not eligible

Expiration Issues

Code Category Description
CAL_0120 Inventory Slot not available anymore
CAL_0121 Itinerary Tour not available anymore
CAL_0122 Itinerary Pricing has changed
CAL_0123 Itinerary Selected date-time closed or invalid

Double Booking Issues

Code Category Description
CAL_0130 Itinerary Duplicate booking attempt within 30 min

Booking Error Codes

Pre-payment Gateway

Code Category Description
CAL_0200 Booking Unknown booking error
CAL_0201 Booking Could not create booking, retry
CAL_0202 Booking Reserved for use

Booking Results Viewing

Code Category Description
CAL_0220 Booking No recent order found
CAL_0221 Booking Booking currency mismatch
CAL_0222 Booking Itinerary vs booking currency mismatch
CAL_0223 Booking Reservation failed via plugin

Expiration

Code Category Description
CAL_0231 Booking Tour prices have changed

Unsupported Operations

Code Category Description
CAL_0241 Booking Unsupported operation for API version

City Error Codes

Code Category Description
CAL_0310 City City not found

Booking UserField Error Codes

Code Category Description
CAL_0600 BookingUserField Incorrect user field
CAL_0601 BookingUserField Missing last name
CAL_0602 BookingUserField Missing mandatory user fields
CAL_0603 BookingUserField Invalid phone number
CAL_0604 BookingUserField Primary customer details missing

Calipso Product Error Codes

Code Category Description
CAL_0900 Product Error in Calipso Product

Partner Error Codes

Code Category Description
CAL_1000 Partner Valid API key not found

Partner Booking Error Codes

Code Category Description
CAL_1300 Booking Count doesn't match number of customers

My Reservations Error Codes

Code Category Description
CAL_1400 Reservations Invalid date range (from > to)
CAL_1401 Reservations Booking does not exist
CAL_1402 Reservations Could not fetch voucher; booking missing
CAL_1403 Reservations Unsupported itinerary type (combo)
CAL_1404 Reservations Authentication failed for voucher
CAL_1405 Reservations Temporary error fetching booking
CAL_1406 Reservations Booking does not belong to user

Springboot Pre-controller Errors

Code Category Description
CAL_1600 Malformed request Invalid body/query/path parameters

Cancellation & Booking Details

Code Category Description
CAL_1801 Cancellation Failed to cancel ticket
CAL_1802 Booking Could not fetch booking (server error)
CAL_1803 Booking Failed to reschedule booking
CAL_1804 Booking Live inventory not available for reschedule

Audio Guide Errors

Code Category Description
CAL_1900 Audio guide Vendor audio guide not found
CAL_1901 Audio guide Could not add audio guide
CAL_1902 Audio guide Audio guide expired
CAL_1903 Audio guide Share limit exceeded
CAL_1904 Audio guide Audio guide unavailable
CAL_1905 Audio guide Unsupported form type
CAL_1906 Audio guide Non-nullable attribute is null
CAL_1907 Audio guide Quote not found
CAL_1908 Audio guide Tour user fields not found

FAQs

Audience and Scope

Who is this FAQ for?

Developers integrating Partner APIs. Technical operations teams can use it for SLA, sandbox, and troubleshooting context. Sales teams should refer to the non-technical brief.

Which endpoints do affiliates vs. API partners use?

  • Affiliates: Catalog-only — cities, categories, collections, products.
  • API partners: Full API suite — catalog, booking, and inventory endpoints for handling transactions.

Environments and Access

Base URLs

Environment Application URL API Base URL
Staging https://sandbox.deimos.dev-headout.com https://sandbox.api.dev-headout.com
Production https://www.headout.com https://www.headout.com

Note: Staging mirrors ~70–80% of production data.

Authentication and Security

How do I authenticate?

Add Headout-Auth: {api-token} to every request.

  • pk_… → production key.
  • tk_… → sandbox key.
  • Enforce HTTPS.
  • Set Content-Type and Accept to application/json.

Are browser-based CORS calls supported?

No. The APIs are server-to-server. Never expose API keys in client apps or public repositories.

What are the key security best practices?

  • Keep API keys private and rotate them when compromised.
  • Log response traceId values for debugging.
  • Minimize PII storage; redact where possible.
  • Enforce HTTPS-only transport.

Why am I seeing Not Allowed … PartnerKeyInvalidException?

Occurs when:

  • The API key is invalid, or
  • The account is not flagged as an API partner.

Resolution: Verify you are using the correct key for the environment. Escalate to your Headout SPOC if the issue persists.

Integration Flow

  1. List active cities via the City API.
  2. Fetch products for the city using the List All Products API.
  3. Retrieve product details and variants with the Product API.
  4. Pull inventory for the variant via the Inventory API.
  5. Create the booking with the Create Booking API (initial status UNCAPTURED).
  6. Capture the booking using the Update Booking API (status moves to PENDING).
  7. Poll booking status or subscribe to webhooks for final status and voucherUrl.

Catalog and Inventory

How is the product catalog structured?

  • City: Top-level aggregation (e.g., Paris).
  • Product: Experience within the city (e.g., Eiffel Tower Guided Tour).
  • Variant: Specific option of a product (e.g., 10 AM tour).
  • Inventory: Date/time slot for the requested pax count.

Curation layers

  • Category: E.g., Tickets.
  • Subcategory: E.g., Landmarks Tickets.
  • Collections: E.g., All Eiffel Tower Tickets.
  • Combos: E.g., Eiffel Tower + Seine Cruise.

How do I list categories and collections for a city?

  • GET /category/list-by/city
  • GET /collections with cityCode
  • Use pagination (offset, limit).

How do I list products for a city?

GET /products with:

  • Required: cityCode
  • Optional: collectionId, categoryId, subCategoryId, languageCode, currencyCode, offset, limit

How large is the catalog?

~5,500 products with ~3 variants per product, growing rapidly.

How do product, variant, and inventory IDs differ?

inventoryId represents a specific date-time slot — distinct from productId and variantId.

Why am I seeing “No inventory/slot”?

  • If availability = UNLIMITED, book immediately.
  • If availability = LIMITED, check the remaining count.
  • Slots may disappear between check and booking, especially on sandbox. Re-check before retrying.

What does error CAL-0120: slot not available indicate?

The slot was taken just before booking. Re-check availability and retry. Escalate if frequent.

Experience available via API but not on the website?

Unexpected. Escalate to your Headout contact.

Booking Creation and Capture

What is partnerReferenceId?

Your internal booking identifier for reconciliation.

Sample booking request (sandbox)

curl --location 'https://sandbox.api.dev-headout.com/api/public/v1/booking' \
  --header 'Headout-Auth: <AUTH>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "variantId": "15786",
    "productId": "8839",
    "inventoryId": "436127621",
    "price": {
      "amount": 13.08,
      "currencyCode": "USD"
    },
    "customersDetails": {
      "count": 1,
      "customers": [
        {
          "personType": "GENERAL",
          "isPrimary": true,
          "inputFields": [
            { "id": "NAME",  "value": "Jonathan Marroquin" },
            { "id": "EMAIL", "value": "asim.kt@gmail.com" },
            { "id": "PHONE", "value": "+919048812190" }
          ]
        }
      ]
    }
  }'

What are the booking status transitions?

  • UNCAPTURED → Booking created.
  • PENDING → Capture requested, fulfillment started.
  • Final states: COMPLETED, CANCELLED, FAILED.
  • CAPTURE_TIMEOUT → Not captured within ~1 hour.

What is the difference between normal and custom input fields?

  • Normal fields: Standard participant data (EMAIL, PHONE, NAME).
  • Custom fields: Product-specific selections (e.g., seat choice). Follow the product details schema to see required fields.

Do I need to collect details for every guest?

Check inputFields.level:

  • ALL → Collect per guest.
  • PRIMARY_CUSTOMER → Only the primary guest.

How do I send custom fields correctly?

Avoid generic IDs such as:

{ "id": "CUSTOM", "name": "Age", "value": "32" }

Instead, use IDs from the Product API:

{ "id": "CUSTOM_144871", "value": "32" }

This prevents “Missing mandatory userFields”.

Why is phone number validation failing?

Use the regex provided in the variant input fields (usually + plus country code).

Which fields are mandatory in a booking request?

  • variantId, inventoryId
  • customersDetails.count
  • price.amount, price.currencyCode
  • Per customer: personType, isPrimary, and product-required inputFields (e.g., EMAIL, PHONE, FULL_NAME, DATE_OF_BIRTH)

Always confirm via GET /products/{productId}.

Booking works without price — is it still required?

Yes. Always send the price object to avoid downstream errors.

Will sandbox send emails or vouchers?

No emails are sent. The API response includes voucherUrl for validation.

What is the turnaround time for non-instant confirmation?

Average ~60 minutes; max 4–6 hours (longer delays are rare but possible).

NOTE: In Sandbox environment, try Instant Confirmation tickets as non-instant confirmation tickets may never be confirmed. (eg. 7809, 1878, 25198, etc.)

How do I test instant confirmation on sandbox?

Product ID QR code on voucher?
8839 No
26149 No
26150 No
15810 Yes

Pricing and Pax

How should I handle age rules and pricing?

  • Use ageFrom / ageTo from the Inventory API.
  • Pricing may be per-person or bundled.
  • For bundles (e.g., group size 4), calculate totals using group pricing and pax min/max.
  • If ageFrom is null, use the upper limit of the CHILD age range.

How do I determine pax limits?

Check pax.min and pax.max at the variant level to validate UI inputs and booking payloads.

Should netPrice equal headoutSellingPrice?

Not unless contractually agreed. Escalate mismatches for pricing review.

How do I support group or bundle pricing?

Leverage pax.min, pax.max, and type fields from the Product API. Validate logic per product.

Caching, Pagination, Formats

What caching strategy do you recommend?

  • Cache product lists/details for ~1 day.
  • Always perform live inventory checks before booking.
  • Never make booking decisions on cached inventory.

How is pagination handled?

Use offset and limit. Responses provide nextUrl, prevUrl, total, and nextOffset.

Which date/time formats are used?

  • ISO 8601 in API requests/responses.
  • Localized yyyy-MM-dd HH:mm:ss may appear in payloads.
  • When both formats exist, ISO startTime takes precedence.
  • Always account for supplier time zones.

Reliability and Escalation

What are the usual debugging steps?

  1. Check the API version.
  2. Verify the API key.
  3. Confirm inventory availability and slot.
  4. Validate request payload and pricing.
  5. Ensure product and variant IDs are not swapped.
  6. Double-check inputFields (common errors include GENERAL vs. ADULT).

How should I report errors?

Provide:

  • Full request body.
  • Full response (untruncated).
  • Request IDs and any supporting context.

What if I hit repeated 500 errors or booking failures?

Retry transiently. Persistent failures are unexpected — escalate with request IDs and redacted payloads. Include the full payload when sharing with Headout, for example:

curl --location 'https://sandbox.api.dev-headout.com/api/public/v1/booking' \
  --header 'Headout-Auth: <AUTH>' \
  --header 'Content-Type: application/json' \
  --data-raw '{...}'  # Include complete payload when escalating

Roadmap and References

What partner-requested features are on the roadmap?

  • Reviews, itinerary fields, combo bookings.
  • Live entertainment seat maps.
  • “Know Before You Go” and “My Tickets”.
  • Search by city + dates + pax.

Where can I find enum glossaries or master lists?

Refer to the shared enums master list in the API documentation. Use Product API responses to map required IDs per product.