Skip to main content
POST
Create a booking

Authorizations

Authorization
string
header
default:sk_test_DEMO0000_replace_with_your_sandbox_key
required

API key authentication. Issued by the Safariat admin or via the partner portal. The secret is shown only once at generation.

Production sk_live_* keys must additionally sign every write request (POST/PUT/DELETE) with the X-Timestamp and X-Signature headers. Sandbox sk_test_* keys are exempt from request signing: X-Signature and X-Timestamp are not required for writes in the sandbox (so the developer-portal "Try it" playground works end to end). The Idempotency-Key header remains required on writes in both environments.

Headers

Idempotency-Key
string
required

Opaque, client-generated string unique per logical operation (a UUID v4 is recommended but any non-blank value up to 255 chars is accepted). Same key + same body = the cached response is returned with the Idempotent-Replayed: true header. Same key + different body = 409 Conflict. Retained for 24 h.

Maximum string length: 255
X-Timestamp
integer<int64>
required

Unix timestamp in seconds at the time the request is issued. Validity window ±5 minutes — beyond that the request is rejected. Required for production sk_live_* keys only; not required for sandbox sk_test_* keys.

X-Signature
string
required

hex(HMAC_SHA256(secret, "{X-Timestamp}\n{METHOD}\n{path}\n{body}")). The path includes the query string. The body is the exact JSON representation sent — any reformatting invalidates the signature. Required for production sk_live_* keys only; not required for sandbox sk_test_* keys.

Pattern: ^[a-f0-9]{64}$

Body

application/json
quote_id
string<uuid>
required
partner_reference
string
required

The bank's internal reference (booking ID on the bank side). Unique per partner. Lets the bank locate the Safariat booking from its own primary key.

Required string length: 1 - 100
traveler
object
required
rooms_allocation
object[]
required
Minimum array length: 1
payment_confirmation
object
required

Payment confirmation supplied by the bank on booking creation (request input).

special_requests
string

Special requests (dietary requirements, accessibility, etc.).

Maximum string length: 1000

Response

Booking created and confirmed

booking_number
string
required
Example:

"MV-AB7X92"

partner_reference
string
required
status
enum<string>
required

The partner channel skips the PENDING status (no payment-wait window). Additional internal Safariat statuses (PAYMENT_PROCESSING, REFUND_PENDING) are never exposed on this API.

Available options:
CONFIRMED,
COMPLETED,
CANCELLED
adventure_slug
string
required
travel_date
string<date>
required
pricing
object
required

Revenue breakdown with the real surcharge recorded at booking (indicative = false).

created_at
string<date-time>
required
traveler
object
required
rooms_allocation
object[]
required
payment_confirmation
object
required

Payment confirmation echoed back on the booking (response projection). The monetary amounts (customer total, net due to Safariat, surcharge) are exposed via pricing.

snapshot_id
string<uuid>
required

ID of the adventure snapshot captured at creation (see ADR-013). Guarantees the traveler receives the experience as it was at the time of booking.

cancellation_tiers
object[]
required
adventure_title
string
traveler_name
string

Initialed (e.g. 'A. B.') for PII protection in lists.

settlement_id
string<uuid> | null

ID of the settlement this booking is included in (null if not yet invoiced).

test_mode
boolean

true when the booking was issued with a sandbox key. A sandbox booking never reaches an operator, never produces a settlement, and its notifications are limited to the traveller address supplied in the request, with a [TEST] subject prefix.

special_requests
string | null
voucher_url
string<uri>

Pre-signed URL to the PDF voucher (7-day TTL).