Create a flight booking

post

https://example.com/v1/flights/bookings

Create a flight booking, optionally attaching a stored travel document
and selecting protection-plan quotes (MER-321).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Flights-only booking creation request.

Extends :class:CreateBookingRequest with two flight-specific fields:

documentId — optional Mercury UUID of a stored travel document
from GET /v1/profile/documents. The document is validated for
ownership and its internal ID is forwarded as travel_document_id
on the booking holder passenger.
insuranceQuotes — optional list of Mercury protection-plan UUIDs
obtained from GET /v1/flights/fares/{fareId}/protection-plans
(MER-321). UUIDs are translated to provider quote IDs at the route
boundary; a stale or unrecognised UUID results in 410 QUOTE_EXPIRED.
Resolved quote IDs are forwarded inline on the booking-create request
so the protection plan binds atomically.

This schema is intentionally limited to POST /v1/flights/bookings
so that documentId and insuranceQuotes do not appear in the
OpenAPI schemas for stays, trains, or cars.

fareId

string

required

Locked fare ID from the search session.

passengers

array of objects

Passenger details. Exactly one adult must have isHolder=true.

Passengers

extraServices

array of objects

deprecated

Deprecated: send all ancillary selections via ancillaries. Still accepted for back-compat; ancillaries takes precedence.

Extraservices

ancillaries

array | null

Unified ancillary selection input. Each item: {id, quantity, passenger_id}. Takes precedence over extraServices when both are provided. For cars, both booking-flow and pay-at-desk selections go here; Mercury routes each to the correct provider bucket by its ancillary kind, so requestServices is no longer needed.

requestServices

array of objects

deprecated

Deprecated (cars only): pay-at-desk selections now belong in the unified ancillaries field, which Mercury routes by ancillary kind. Still accepted for back-compat.

Requestservices

tripId

Optional trip to associate this booking with. When provided, a TripSegment record is persisted linking the booking to the trip.

isPersonal

Whether this is a personal (non-business) booking.

phone

Contact phone number for the booking.

invoiceProfileId

Invoice profile to use for this booking. Auto-resolved when omitted.

billingAddressId

Billing address to associate with this booking. Auto-resolved from the invoice profile when omitted.

customFields

object | null

Answers to the account's custom fields for this vertical, keyed by definition key (from GET /v1/custom-fields). Values: string for text/single_select (option key) and date (YYYY-MM-DD), list of option keys for multi_select. Answers are validated against the account's definitions; any invalid answer fails the request with a field-level 422. An empty value ("" or []) means unanswered and is stripped at the boundary, so it is treated identically to omitting the key.

documentId

Mercury UUID of a stored travel document (from GET /v1/profile/documents). When provided the document is validated for ownership and forwarded as travel_document_id on the holder passenger.

insuranceQuotes

array | null

Optional list of protection-plan Mercury UUIDs from GET /v1/flights/fares/{fareId}/protection-plans. UUIDs are translated to provider quote IDs before forwarding.

Headers

Idempotency-Key

Client-generated idempotency key (UUID v4 recommended). Required on all booking mutation requests to prevent duplicate bookings on retry.

Responses

401

Missing or invalid authentication, or the provider rejected the forwarded travel-document credential

403

User lacks booking capability for this vertical, or the provider denied the travel-document lookup (resolved deny)

404

Fare not found or expired, or tripId inaccessible

409

Booking already exists (conflict)

422

Validation error, invalid documentId, missing passenger document, or missing header

503

Booking or travel document service not configured

Language

Credentials

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Successful Response