cURL

curl --location 'https://www.headout.com/api/public/v1/booking/' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "variantId": "2671",
  "inventoryId": "402612775",
  "customersDetails": {
      "count": 1,
      "customers": [
          {
              "personType": "GENERAL",
              "isPrimary": true,
              "inputFields": [
                  {
                      "id": "NAME",
                      "value": "adult test"
                  },
                  {
                      "id": "EMAIL",
                      "value": "test@email.com"
                  },
                  {
                      "id": "PHONE",
                      "value": "+919888888787"
                  },
                  {
                      "id": "CUSTOM_97179",
                      "value": "some pickup point"
                  },
                  {
                      "id": "CUSTOM_125551",
                      "value": "+919888888787"
                  }
              ]
          }
      ]
  },
  "price": {
      "amount": 120.0,
      "currencyCode": "AED"
  }
}'

import requests

url = "https://www.headout.com/api/public/v1/booking/"

payload = {
    "variantId": "<string>",
    "inventoryId": "<string>",
    "customersDetails": {
        "count": 123,
        "customers": [
            {
                "personType": "<string>",
                "isPrimary": True,
                "inputFields": [
                    {
                        "id": "<string>",
                        "value": "<string>"
                    }
                ]
            }
        ]
    },
    "productId": "<string>",
    "inventorySeatIds": ["<string>"],
    "variantInputFields": [
        {
            "id": "<string>",
            "value": "<string>"
        }
    ],
    "price": {
        "amount": 123,
        "currencyCode": "<string>"
    }
}
headers = {
    "Headout-Auth": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Headout-Auth': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    variantId: '<string>',
    inventoryId: '<string>',
    customersDetails: {
      count: 123,
      customers: [
        {
          personType: '<string>',
          isPrimary: true,
          inputFields: [{id: '<string>', value: '<string>'}]
        }
      ]
    },
    productId: '<string>',
    inventorySeatIds: ['<string>'],
    variantInputFields: [{id: '<string>', value: '<string>'}],
    price: {amount: 123, currencyCode: '<string>'}
  })
};

fetch('https://www.headout.com/api/public/v1/booking/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.headout.com/api/public/v1/booking/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'variantId' => '<string>',
    'inventoryId' => '<string>',
    'customersDetails' => [
        'count' => 123,
        'customers' => [
                [
                                'personType' => '<string>',
                                'isPrimary' => true,
                                'inputFields' => [
                                                                [
                                                                                                                                'id' => '<string>',
                                                                                                                                'value' => '<string>'
                                                                ]
                                ]
                ]
        ]
    ],
    'productId' => '<string>',
    'inventorySeatIds' => [
        '<string>'
    ],
    'variantInputFields' => [
        [
                'id' => '<string>',
                'value' => '<string>'
        ]
    ],
    'price' => [
        'amount' => 123,
        'currencyCode' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Headout-Auth: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.headout.com/api/public/v1/booking/"

	payload := strings.NewReader("{\n  \"variantId\": \"<string>\",\n  \"inventoryId\": \"<string>\",\n  \"customersDetails\": {\n    \"count\": 123,\n    \"customers\": [\n      {\n        \"personType\": \"<string>\",\n        \"isPrimary\": true,\n        \"inputFields\": [\n          {\n            \"id\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    ]\n  },\n  \"productId\": \"<string>\",\n  \"inventorySeatIds\": [\n    \"<string>\"\n  ],\n  \"variantInputFields\": [\n    {\n      \"id\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"price\": {\n    \"amount\": 123,\n    \"currencyCode\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Headout-Auth", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.headout.com/api/public/v1/booking/")
  .header("Headout-Auth", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"variantId\": \"<string>\",\n  \"inventoryId\": \"<string>\",\n  \"customersDetails\": {\n    \"count\": 123,\n    \"customers\": [\n      {\n        \"personType\": \"<string>\",\n        \"isPrimary\": true,\n        \"inputFields\": [\n          {\n            \"id\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    ]\n  },\n  \"productId\": \"<string>\",\n  \"inventorySeatIds\": [\n    \"<string>\"\n  ],\n  \"variantInputFields\": [\n    {\n      \"id\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"price\": {\n    \"amount\": 123,\n    \"currencyCode\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.headout.com/api/public/v1/booking/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Headout-Auth"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"variantId\": \"<string>\",\n  \"inventoryId\": \"<string>\",\n  \"customersDetails\": {\n    \"count\": 123,\n    \"customers\": [\n      {\n        \"personType\": \"<string>\",\n        \"isPrimary\": true,\n        \"inputFields\": [\n          {\n            \"id\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    ]\n  },\n  \"productId\": \"<string>\",\n  \"inventorySeatIds\": [\n    \"<string>\"\n  ],\n  \"variantInputFields\": [\n    {\n      \"id\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"price\": {\n    \"amount\": 123,\n    \"currencyCode\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "bookingId": "126890",
  "voucherId": "415872",
  "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=AAAD6AAAABhsDVGl...",
  "tickets": []
}

{
  "timestamp": 1787825956750,
  "traceId": "5bc7926d5ffe466c",
  "traceTokenOriginal": "892b5cc0f80f832e10b1be8a7d0702be",
  "error": {
    "code": "E_RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again in 26m 48s."
  }
}

Bookings

Create a new booking

We are soon moving to v2 APIs and v1 will be deprecated. Switch to v2 using the version selector above.

Create a new booking in UNCAPTURED state.

The booking flow is two-step: call this endpoint first to reserve the slot and receive a bookingId, then call Update Booking to capture the booking and trigger fulfillment. Bookings not captured within one hour are automatically moved to CAPTURE_TIMEDOUT.

Rate limit: Create Booking is capped at 100 requests per rolling 30-minute window per API key. The limit counts every request received — successful (200), failed (e.g. 400), and requests already rejected with 429 all count toward the window, not just bookings created. Once you cross the limit, requests return 429 Too Many Requests with error.code = E_RATE_LIMIT_EXCEEDED. The response includes a retry-after header with the number of seconds to wait (e.g. 1608), and the error message states the same wait time in human-readable form. Use the retry-after value to schedule your next call.

POST

api

public

booking

cURL

curl --location 'https://www.headout.com/api/public/v1/booking/' \
--header 'Headout-Auth: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "variantId": "2671",
  "inventoryId": "402612775",
  "customersDetails": {
      "count": 1,
      "customers": [
          {
              "personType": "GENERAL",
              "isPrimary": true,
              "inputFields": [
                  {
                      "id": "NAME",
                      "value": "adult test"
                  },
                  {
                      "id": "EMAIL",
                      "value": "test@email.com"
                  },
                  {
                      "id": "PHONE",
                      "value": "+919888888787"
                  },
                  {
                      "id": "CUSTOM_97179",
                      "value": "some pickup point"
                  },
                  {
                      "id": "CUSTOM_125551",
                      "value": "+919888888787"
                  }
              ]
          }
      ]
  },
  "price": {
      "amount": 120.0,
      "currencyCode": "AED"
  }
}'

import requests

url = "https://www.headout.com/api/public/v1/booking/"

payload = {
    "variantId": "<string>",
    "inventoryId": "<string>",
    "customersDetails": {
        "count": 123,
        "customers": [
            {
                "personType": "<string>",
                "isPrimary": True,
                "inputFields": [
                    {
                        "id": "<string>",
                        "value": "<string>"
                    }
                ]
            }
        ]
    },
    "productId": "<string>",
    "inventorySeatIds": ["<string>"],
    "variantInputFields": [
        {
            "id": "<string>",
            "value": "<string>"
        }
    ],
    "price": {
        "amount": 123,
        "currencyCode": "<string>"
    }
}
headers = {
    "Headout-Auth": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Headout-Auth': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    variantId: '<string>',
    inventoryId: '<string>',
    customersDetails: {
      count: 123,
      customers: [
        {
          personType: '<string>',
          isPrimary: true,
          inputFields: [{id: '<string>', value: '<string>'}]
        }
      ]
    },
    productId: '<string>',
    inventorySeatIds: ['<string>'],
    variantInputFields: [{id: '<string>', value: '<string>'}],
    price: {amount: 123, currencyCode: '<string>'}
  })
};

fetch('https://www.headout.com/api/public/v1/booking/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.headout.com/api/public/v1/booking/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'variantId' => '<string>',
    'inventoryId' => '<string>',
    'customersDetails' => [
        'count' => 123,
        'customers' => [
                [
                                'personType' => '<string>',
                                'isPrimary' => true,
                                'inputFields' => [
                                                                [
                                                                                                                                'id' => '<string>',
                                                                                                                                'value' => '<string>'
                                                                ]
                                ]
                ]
        ]
    ],
    'productId' => '<string>',
    'inventorySeatIds' => [
        '<string>'
    ],
    'variantInputFields' => [
        [
                'id' => '<string>',
                'value' => '<string>'
        ]
    ],
    'price' => [
        'amount' => 123,
        'currencyCode' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Headout-Auth: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.headout.com/api/public/v1/booking/"

	payload := strings.NewReader("{\n  \"variantId\": \"<string>\",\n  \"inventoryId\": \"<string>\",\n  \"customersDetails\": {\n    \"count\": 123,\n    \"customers\": [\n      {\n        \"personType\": \"<string>\",\n        \"isPrimary\": true,\n        \"inputFields\": [\n          {\n            \"id\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    ]\n  },\n  \"productId\": \"<string>\",\n  \"inventorySeatIds\": [\n    \"<string>\"\n  ],\n  \"variantInputFields\": [\n    {\n      \"id\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"price\": {\n    \"amount\": 123,\n    \"currencyCode\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Headout-Auth", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.headout.com/api/public/v1/booking/")
  .header("Headout-Auth", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"variantId\": \"<string>\",\n  \"inventoryId\": \"<string>\",\n  \"customersDetails\": {\n    \"count\": 123,\n    \"customers\": [\n      {\n        \"personType\": \"<string>\",\n        \"isPrimary\": true,\n        \"inputFields\": [\n          {\n            \"id\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    ]\n  },\n  \"productId\": \"<string>\",\n  \"inventorySeatIds\": [\n    \"<string>\"\n  ],\n  \"variantInputFields\": [\n    {\n      \"id\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"price\": {\n    \"amount\": 123,\n    \"currencyCode\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.headout.com/api/public/v1/booking/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Headout-Auth"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"variantId\": \"<string>\",\n  \"inventoryId\": \"<string>\",\n  \"customersDetails\": {\n    \"count\": 123,\n    \"customers\": [\n      {\n        \"personType\": \"<string>\",\n        \"isPrimary\": true,\n        \"inputFields\": [\n          {\n            \"id\": \"<string>\",\n            \"value\": \"<string>\"\n          }\n        ]\n      }\n    ]\n  },\n  \"productId\": \"<string>\",\n  \"inventorySeatIds\": [\n    \"<string>\"\n  ],\n  \"variantInputFields\": [\n    {\n      \"id\": \"<string>\",\n      \"value\": \"<string>\"\n    }\n  ],\n  \"price\": {\n    \"amount\": 123,\n    \"currencyCode\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "bookingId": "126890",
  "voucherId": "415872",
  "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=AAAD6AAAABhsDVGl...",
  "tickets": []
}

{
  "timestamp": 1787825956750,
  "traceId": "5bc7926d5ffe466c",
  "traceTokenOriginal": "892b5cc0f80f832e10b1be8a7d0702be",
  "error": {
    "code": "E_RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again in 26m 48s."
  }
}

Authorizations

Headout-Auth

string

header

required

Body

application/json

variantId

string

required

The variant (tour option) to book. Obtain from the product's variants list.

inventoryId

string

required

The specific inventory slot (time/date) to book. Obtain from the inventory listing endpoint.

customersDetails

object

required

Information about all customers included in this booking.

Show child attributes

productId

string

The product to book. Obtain from the product listing endpoints.

inventorySeatIds

string[] | null

Specific seat IDs to reserve, for seatmap-based products. Omit for non-seatmap products.

variantInputFields

object[] | null

Booking-level input fields applicable to the whole booking rather than individual customers.

Show child attributes

price

object

Total booking price — the sum of the inventory netPrice field across all pax types. Use netPrice, not price or headoutSellingPrice. Validated against current inventory pricing to prevent stale-price bookings.

Show child attributes

Response

Booking created successfully

bookingId

string

Headout's unique identifier for this booking. Use this bookingId for all subsequent operations (capture, cancel, reschedule).

voucherId

string

Identifier of the voucher issued for this booking. Pass it to Get a voucher to retrieve the structured voucher payload.

partnerReferenceId

string | null

Your own reference ID for this booking, set when capturing. Useful for correlating Headout bookings with your internal order system.

variantId

string

The variant (tour option) that was booked.

startDateTime

string<date-time>

Scheduled start time for the experience in local time, with no timezone offset (format yyyy-MM-dd'T'HH:mm:ss).

product

object

Summary of the product and variant booked.

Show child attributes

customersDetails

object

All customers included in this booking.

Show child attributes

variantInputFields

object[]

Show child attributes

price

object

Total price paid for this booking.

Show child attributes

status

enum<string>

Current lifecycle state of the booking. See Booking Status.

UNCAPTURED: Created but not yet captured. Does not lock inventory or price. Auto-expires to CAPTURE_TIMEDOUT after 1 hour.
PENDING: Payment captured — confirmed with supplier. Treat as confirmed; show to the customer as a confirmed booking.
COMPLETED: Fulfilled — tickets are available in the tickets array.
CANCELLED: Cancelled by partner, customer, or Headout.
FAILED: Booking failed due to a payment or system error.
CAPTURE_TIMEDOUT: Not captured within 1 hour of creation; can no longer be captured.

Available options:

UNCAPTURED,

PENDING,

COMPLETED,

CANCELLED,

FAILED,

CAPTURE_TIMEDOUT

voucherUrl

string

URL to the booking voucher PDF. Available once the booking reaches PENDING or COMPLETED status.

tickets

object[] | null

Individual tickets associated with this booking. Populated after successful fulfillment.

Show child attributes

seatInfo

object[] | null

Seat assignment details for seatmap-based products. Null for non-seatmap products.

Show child attributes

creationTimestamp

integer<int64>

Unix epoch timestamp (seconds) when this booking was first created.

Guide

Cities

Categories

Products

Inventory

Bookings

Create a new booking

Authorizations

Body

Response