Zim developer docs

Everything you need to build
travel workflows on Zim

REST API reference for travel request orchestration, policy enforcement, tenant management, and Stripe-powered booking execution.

Quick Start → Back to homepage
Quick start

Authenticate, create a request, orchestrate booking

# Base URL
https://zim.global

# Required header
X-Api-Key: YOUR_API_KEY

# Create a travel request from natural language
curl -X POST https://zim.global/v1/requests \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "tenant_id": "default",
    "traveler_id": "default",
    "raw_message": "Book me a business trip from London to Dubai next Friday",
    "auto_search": true,
    "metadata": {"source": "agent"}
  }'

What Zim does

Zim gives your agent one REST layer for travel intent capture, search orchestration, option selection, traveler collection, approval workflows, Stripe-backed execution, fulfillment updates, and admin management.

Requests
Trips
Policies
Travelers
Tenants
Stripe
Authentication

API key header

Required on API requests

🔑
X-Api-KeyPass your API key in the X-Api-Key header on authenticated calls.
🌐
Base URLUse https://zim.global and append the versioned path, such as /v1/requests.
📦
JSON bodiesSend Content-Type: application/json for POST and PUT payloads.
curl https://zim.global/v1/health \
  -H "X-Api-Key: YOUR_API_KEY"
Core booking flow

Request lifecycle and orchestration endpoints

Zim models booking as a request state machine. You can start from structured intent or a raw natural-language message, then progress through search, selection, traveler collection, approval, execution, payment, and fulfillment.

intent_received
→
searching
→
options_ready
→
selected
→
traveler_info_submitted
→
pending_approval
→
approved
→
executing
→
completed
Alternative states: failed
Alternative states: cancelled
Retry allowed from options_ready or failed

POST/v1/requests

Create a new travel request from structured intent or a raw natural-language prompt. If auto_search is true, Zim searches immediately.

curl -X POST https://zim.global/v1/requests \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "tenant_id": "default",
    "traveler_id": "default",
    "intent": {
      "origin": "LHR",
      "destination": "DXB",
      "departure_date": "2026-04-24",
      "travelers": 1,
      "cabin_class": "business"
    },
    "auto_search": true
  }'

GET/v1/requests

List requests with optional filters: tenant_id, traveler_id, state, limit, offset.

GET/v1/requests/{request_id}

Fetch the full state of a specific travel request including current status, options, selection state, payment state, and fulfillment details.

POST/search

Trigger search on a request created with auto_search=false. Valid from intent_received.

POST/select

Select flight_index, hotel_index, and car_index from prepared search results.

POST/traveler-info

Submit traveler fields such as name, DOB, passport details, email, phone, and frequent flyer info.

POST/approve

Submit approval decision with decision and optional notes.

POST/execute

Trigger booking execution. Zim creates a Stripe checkout session and runs the executor flow.

POST/cancel

Cancel a request that should not continue to booking.

POST/retry

Re-search a request from options_ready or failed. Zim resets state and starts a new search pass.

GET/payment-status

Return payment state and Stripe session details for the current request.

Example orchestration sequence

1. Create
POST /v1/requests
Create from raw_message or structured intent.
2. Search
POST /v1/requests/{request_id}/search
Only needed when auto_search=false.
3. Select
POST /v1/requests/{request_id}/select
Choose flight, hotel, and car indexes.
4. Traveler + approval
POST /traveler-info → POST /approve
Collect passenger data and approval decision.
5. Execute + pay
POST /execute → GET /payment-status
Launch Stripe checkout and monitor payment state.
Trips & health

Read completed trips and service status

GET/v1/trips

List completed trips with filters: tenant_id, traveler_id, created_after, created_before, limit, and offset.

GET/v1/trips/{trip_id}

Fetch the full details of a completed trip record.

GET/v1/health

Simple health check endpoint for uptime monitoring and integration verification.

Admin API

Tenants, policies, travelers, and stats

Zim includes admin endpoints for multi-tenant configuration, policy management, traveler directory records, and dashboard metrics.

Tenants

P
POST /v1/admin/tenantsCreate tenant with name, domain, and settings.
G
GET /v1/admin/tenantsList tenants. Supports include_deleted, limit, offset.
I
GET /v1/admin/tenants/{tenant_id}Get one tenant by id.
U
PUT /v1/admin/tenants/{tenant_id}Update tenant fields.
D
DELETE /v1/admin/tenants/{tenant_id}Soft-delete a tenant.

Policies

P
POST /v1/admin/policiesCreate policy with tenant_id, name, is_default, and policy object.
G
GET /v1/admin/policiesList policies, optionally filtered by tenant_id.
I
GET /v1/admin/policies/{policy_id}Get one policy.
U
PUT /v1/admin/policies/{policy_id}Update name, default flag, or policy object.
D
DELETE /v1/admin/policies/{policy_id}Soft-delete a policy.

Travelers

P
POST /v1/admin/travelersCreate traveler with tenant_id, name, email, phone, preferences, frequent_flyer, and passport_info.
G
GET /v1/admin/travelersList travelers, optionally filtered by tenant.
I
GET /v1/admin/travelers/{traveler_id}Get a traveler record.
U
PUT /v1/admin/travelers/{traveler_id}Update traveler data and preferences.

Admin stats

GET /v1/admin/stats returns aggregate stats for the admin dashboard and can be filtered by tenant_id.

curl https://zim.global/v1/admin/stats?tenant_id=default \
  -H "X-Api-Key: YOUR_API_KEY"
AreaCreate body fieldsNotes
Tenantname, domain, settingsMulti-tenant partition root.
Policytenant_id, name, is_default, policyStores approval, budget, or vendor rules as an object.
Travelertenant_id, name, email, phone, preferences, frequent_flyer, passport_infoDirectory and preference memory for booking flows.
Webhooks

Stripe payment events

POST/v1/webhooks/stripe

Zim handles Stripe webhook events and updates payment state. When STRIPE_WEBHOOK_SECRET is configured, the Stripe-Signature header is verified.

checkout.session.completed
payment_intent.succeeded
checkout.session.expired
payment_intent.payment_failed
charge.refunded

Webhook behavior

✓
PaidCompleted checkout and successful payment intents move the request payment state to paid.
!
FailedExpired sessions and failed payment intents move payment state to failed.
↺
RefundedRefund events update request payment state to refunded.
#
IdempotentDuplicate Stripe event IDs are treated as no-ops.
Schemas

Key request bodies and fields

CreateRequestBody

{
  "tenant_id": "default",
  "traveler_id": "default",
  "intent": {
    "origin": "LHR",
    "destination": "DXB",
    "departure_date": "2026-04-24",
    "return_date": "2026-04-27",
    "travelers": 1,
    "cabin_class": "business",
    "hotel_destination": "Dubai",
    "check_in": "2026-04-24",
    "check_out": "2026-04-27",
    "car_location": "DXB"
  },
  "raw_message": "Book me a business trip to Dubai next Friday",
  "auto_search": true,
  "metadata": {"source": "agent"}
}

SelectOptionsBody

{
  "flight_index": 0,
  "hotel_index": 1,
  "car_index": 0
}

ApprovalBody

{
  "decision": "approve",
  "notes": "Within policy"
}

TravelerInfoBody

{
  "first_name": "Robin",
  "last_name": "Zieme",
  "date_of_birth": "1980-01-01",
  "gender": "male",
  "passport_number": "123456789",
  "passport_expiry": "2030-01-01",
  "passport_country": "SE",
  "email": "robin@example.com",
  "phone": "+971...",
  "frequent_flyer": {"EK": "12345"}
}

FulfillmentUpdateBody

{
  "fulfillment_state": "ticketed",
  "details": {
    "pnr": "ABC123",
    "provider": "amadeus"
  }
}
SchemaImportant fieldsDescription
StructuredIntentorigin, destination, departure_date, return_date, travelers, cabin_class, hotel_destination, check_in, check_out, car_locationNormalized travel intent used to drive search.
CreateTenantBodyname, domain, settingsCreate a tenant namespace.
CreatePolicyBodytenant_id, name, is_default, policyCreate policy objects for budget, approval, and routing rules.
CreateTravelerBodytenant_id, name, email, phone, preferences, frequent_flyer, passport_infoCreate traveler directory records.