Universal API

v1.0.0

The iVector Universal API is a multi-tenant API gateway providing unified access to travel booking and management services. It acts as a proxy to downstream backend APIs — handling authentication, tenant resolution, and credential management centrally.

API Version & URL Structure

All endpoints are versioned with a /v1/ prefix. The base URL structure is:


https://<host>/v1/booking/...       (Booking Services endpoints)
https://<host>/v1/core/...          (Core Services endpoints)
https://<host>/v1/ops/{module}/...  (Ops Services — operational tools, one path per module)

Authentication

All requests require an API key passed in the x-api-key HTTP header:


x-api-key: your_api_key_here

To obtain an API key, contact Intuitive and we will create one for you in AWS. Each API key is associated with a specific tenant and environment (e.g., Test or Live), and determines which backend system your requests are routed to.

Content Type

Error Handling

Errors are returned with an appropriate HTTP status code and a JSON body containing a machine-readable error code and a human-readable message:


{
  "code": "ERROR_CODE",
  "message": "Human-readable error description"
}

HTTP Status Codes:

| Status | Error Code | Description |

|--------|-----------|-------------|

| 400 | GATEWAY_BAD_REQUEST | The request was malformed or contained invalid parameters |

| 401 | GATEWAY_UNAUTHORIZED | Invalid or missing API key |

| 403 | GATEWAY_TENANT_DISABLED | Tenant account is disabled |

| 422 | GATEWAY_VALIDATION_ERROR | Request body failed validation |

| 429 | GATEWAY_RATE_LIMITED | Rate limit exceeded |

| 500 | GATEWAY_INTERNAL_ERROR | Unexpected internal server error |

| 502 | GATEWAY_BACKEND_ERROR | Backend service returned an error |

| 504 | GATEWAY_BACKEND_TIMEOUT | Backend service did not respond in time |

Example — Server Error (500):


{
  "code": "GATEWAY_INTERNAL_ERROR",
  "message": "An unexpected error occurred while processing your request."
}

Example — Validation Error (422):


{
  "code": "GATEWAY_VALIDATION_ERROR",
  "message": "Validation failed: 'arrival_date' is required; 'duration' must be between 1 and 30."
}

Downstream APIs

Booking Services

A comprehensive travel booking API that enables search, pricing, and booking of travel components including properties, flights, transfers, car hire, and extras. Endpoints are prefixed with /v1/booking/.

A typical booking flow follows these steps:

  1. Search — Find available options (e.g., /v1/booking/properties/search)
  2. Prebook — Get detailed pricing and availability (e.g., /v1/booking/properties/prebook)
  3. Add to Basket — Combine multiple components in a basket
  4. Book — Confirm the booking with payment details (/v1/booking/basket/book)

Core Services

A REST/JSON CRUD API providing direct access to system tables for administration, configuration, and data management. Endpoints are prefixed with /v1/core/. In addition to the standard API key, Core Services requests require an X-SystemUser-Email header identifying the system user performing the operation.

Ops Services

Operational endpoints surfacing iVector business modules — pricing, inventory, etc. — that don't fit a single CRUD table. Endpoints are organised by module under /v1/ops/{module}/... (for example /v1/ops/flights/charter-flight-pricing). Each module is backed by a separate downstream service per environment, but all share the same authentication contract: API key plus an X-SystemUser-Email header identifying the system user performing the operation.

Tools

Booking Services

Booking & search API — /v1/booking/

Core Services

CRUD administration API — /v1/core/