Getting started with the Mercury API

Mercury is BizAway's traveler-facing REST API for searching and booking
flights, stays, cars, and trains. This guide walks you through making your
first authenticated request against the /v1 surface.

Prerequisites

• A BizAway tenant with API access enabled.
• A registered consumer with a signing secret (see
  Authentication).
• A traveler bearer token for the person you are acting on behalf of,
  obtained from the login endpoints.
• The Mercury API base URL for your environment. Reach out to your BizAway
  integration contact if you do not yet have credentials or a host.
• A REST client (curl, HTTPie, Bruno, Postman, or your language's HTTP
  library of choice).

API versioning

All endpoints documented in the API Reference
are versioned under /v1. New versions, when introduced, are published
under /v2 without breaking /v1. See
Errors and pagination for the compatibility
policy.

Authentication

Every request is authenticated on two axes:

1. Consumer HMAC (primary) — a signature that identifies your client
   application, sent as the Bizaway-Consumer, Bizaway-Timestamp, and
   Bizaway-Signature headers.
2. Bearer token — the traveler's identity JWT in the Authorization
   header.

The full signing algorithm, worked examples in bash/Python/Node, secret
rotation, and troubleshooting live in the
Authentication guide. A minimal signed request looks
like this:

curl "$MERCURY_BASE_URL/v1/profile" \
  -H "Bizaway-Consumer: $CONSUMER" \
  -H "Bizaway-Timestamp: $TIMESTAMP" \
  -H "Bizaway-Signature: $SIGNATURE" \
  -H "Authorization: Bearer $TRAVELER_JWT"

If the consumer signature is missing or invalid, the API returns 401 with a
CONSUMER_AUTH_REQUIRED error envelope. If the bearer token is missing,
expired, or invalid, it returns 401 with the standard error envelope.

Your first request

Fetch the authenticated traveler's profile (a GET, so the signed body hash is
the SHA-256 of the empty string):

curl "$MERCURY_BASE_URL/v1/profile" \
  -H "Bizaway-Consumer: $CONSUMER" \
  -H "Bizaway-Timestamp: $TIMESTAMP" \
  -H "Bizaway-Signature: $SIGNATURE" \
  -H "Authorization: Bearer $TRAVELER_JWT"

A successful response returns the traveler's profile record as JSON.

The booking flow at a glance

Every travel vertical follows the same four-step shape:

1. Search — POST /v1/{vertical}/search streams normalised solutions back
   as Server-Sent Events.
2. List fares — POST /v1/{vertical}/fares streams the bookable fares for a
   chosen solution.
3. Build fare — POST /v1/{vertical}/fares/build locks a specific fare and
   returns a fareId.
4. Book — POST /v1/{vertical}/bookings creates the booking from the built
   fareId.

What's next

• Authentication — sign your requests.
• Search and book each vertical:
  Flights, Stays,
  Trains, Cars.
• Bookings and trips — manage the booking lifecycle and organise trips.
• Errors and pagination — handle error envelopes and paged lists.
• API Reference — the full OpenAPI reference for
  every endpoint, request schema, and response shape.

Reporting issues

This page is maintained by the BizAway integration team. To request changes or
report an error, contact your BizAway integration contact. Edits made directly
in the ReadMe dashboard are overwritten on the next publish.